Provided by: libmotif-dev_2.3.8-2build1_amd64 bug

NAME

       XmDropSite — The DropSite Registry "XmDropSite"

SYNOPSIS

       #include <Xm/DragDrop.h>

DESCRIPTION

       A  client  registers  a  widget  or  gadget  as  a  drop site using the XmDropSiteRegister
       function. In addition, this routine defines the behavior and capabilities of a  drop  site
       by   specifying   appropriate   resources.   For   example,   the   XmNimportTargets   and
       XmNnumImportTargets resources identify respectively the selection target types and  number
       of  types  supported  by  a drop site. The visual animation effects associated with a drop
       site are also described with DropSite resources.

       Drop site animation effects that occur in response to the pointer entering  a  valid  drop
       site  are  called  drag-under effects. A receiver can select from several animation styles
       supplied by the toolkit or can provide customized animation  effects.  Drag-under  effects
       supplied  by  the  toolkit  include border highlighting, shadow in/out drawing, and pixmap
       representation.

       When a preregister drag protocol style is used, the toolkit  generates  drag-under  visual
       effects based on the value of the XmNanimationStyle resource. In dynamic mode, if the drop
       site XmNdragProc resource is NULL, the toolkit also provides animation  effects  based  on
       the  XmNanimationStyle  resource.  Otherwise, if the XmNdragProc routine is specified, the
       receiver can either assume responsibility for animation effects (through  the  XmNdragProc
       routine)  or  rely  on the toolkit to provide animation.  An application can either handle
       all or none of the animation effects for a particular drop site.  That is, an  application
       should never do a partial job of animation on a particular drop site.

       Drop  sites  may overlap. The initial stacking order corresponds to the order in which the
       drop sites were registered. When a drop site overlaps another drop  site,  the  drag-under
       effects of the drop site underneath are clipped by the obscuring drop site(s).

       The  XmDropSiteUpdate  routine  sets  resources  for a widget that is registered as a drop
       site. XmDropSiteRetrieve gets  drop  site  resource  values  previously  specified  for  a
       registered widget. These routines are used instead of XtSetValues and XtGetValues.

   Classes
       XmDropSite does not inherit from any widget class.

   New Resources
       The  following  table  defines a set of widget resources used by the programmer to specify
       data. To reference a resource by name or by class in a .Xdefaults file, remove the XmN  or
       XmC  prefix  and  use  the  remaining  letters. To specify one of the defined values for a
       resource in a .Xdefaults file, remove the Xm 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  XmDropSiteUpdate  (S),  retrieved  by  using  XmDropSiteRetrieve  (G),  or  is  not
       applicable (N/A).

       ┌────────────────────────────────────────────────────────────────────────────────────────────────────────┐
       │                        │               XmDropSiteResource Set    │                           │        │
       │NameClassTypeDefaultAccess │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNanimationMask        │ XmCAnimationMask        │ Pixmap         │ XmUNSPECIFIED_PIXMAP      │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNanimationPixmap      │ XmCAnimationPixmap      │ Pixmap         │ XmUNSPECIFIED_PIXMAP      │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNanimationPixmapDepth │ XmCAnimationPixmapDepth │ int            │ 0                         │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNanimationStyle       │ XmCAnimationStyle       │ unsigned char  │ XmDRAG_UNDER_HIGHLIGHT    │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdragProc             │ XmCDragProc             │ XtCallbackProc │ NULL                      │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdropProc             │ XmCDropProc             │ XtCallbackProc │ NULL                      │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdropRectangles       │ XmCDropRectangles       │ XRectangle *   │ dynamic                   │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdropSiteActivity     │ XmCDropSiteActivity     │ unsigned char  │ XmDROP_SITE_ACTIVE        │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdropSiteOperations   │ XmCDropSiteOperations   │ unsigned char  │ XmDROP_MOVE | XmDROP_COPY │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNdropSiteType         │ XmCDropSiteType         │ unsigned char  │ XmDROP_SITE_SIMPLE        │ CG     │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNimportTargets        │ XmCImportTargets        │ Atom *         │ NULL                      │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNnumDropRectangles    │ XmCNumDropRectangles    │ Cardinal       │ 1                         │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       │XmNnumImportTargets     │ XmCNumImportTargets     │ Cardinal       │ 0                         │ CSG    │
       ├────────────────────────┼─────────────────────────┼────────────────┼───────────────────────────┼────────┤
       └────────────────────────┴─────────────────────────┴────────────────┴───────────────────────────┴────────┘
       XmNanimationMask
                 Specifies a mask to use with the pixmap specified by XmNanimationPixmap when the
                 animation style is XmDRAG_UNDER_PIXMAP.

       XmNanimationPixmap
                 Specifies  a  pixmap  for  drag-under  animation  when  the  animation  style is
                 XmDRAG_UNDER_PIXMAP. The pixmap is drawn with  its  origin  at  the  upper  left
                 corner  of  the bounding box of the drop site. If the drop site window is larger
                 than the animation pixmap, the portion of the window not covered by  the  pixmap
                 will be tiled with the window's background color.

       XmNanimationPixmapDepth
                 Specifies  the depth of the pixmap specified by the XmNanimationPixmap resource.
                 When the depth is 1, the colors are taken from the foreground and background  of
                 the  drop  site  widget. For any other value, drop site animation occurs only if
                 the XmNanimationPixmapDepth matches the depth of the drop  site  window.  Colors
                 are derived from the current colormap.

       XmNanimationStyle
                 Specifies  the  drag-under  animation style used when a drag enters a valid drop
                 site. The possible values are

                 XmDRAG_UNDER_HIGHLIGHT
                           The drop site uses highlighting effects.

                 XmDRAG_UNDER_SHADOW_OUT
                           The drop site uses an outset shadow.

                 XmDRAG_UNDER_SHADOW_IN
                           The drop site uses an inset shadow.

                 XmDRAG_UNDER_PIXMAP
                           The drop site uses  the  pixmap  specified  by  XmNanimationPixmap  to
                           indicate that it can receive the drop.

                 XmDRAG_UNDER_NONE
                           The drop site does not use animation effects. A client using a dynamic
                           protocol, may provide drag-under effects in its XmNdragProc routine.

       XmNdragProc
                 Specifies the procedure that is invoked when the drop site receives a  crossing,
                 motion,  or  operation  changed  message.  This  procedure is called only when a
                 dynamic protocol is used.  The type of structure whose address is passed to this
                 procedure  is XmDragProcCallbackStruct.  The reason sent to the procedure is one
                 of the following:

                    •  XmCR_DROP_SITE_ENTER_MESSAGEXmCR_DROP_SITE_LEAVE_MESSAGEXmCR_DRAG_MOTIONXmCR_OPERATION_CHANGED

                 The  drag  procedure  may  change  the   values   of   some   members   of   the
                 XmDragProcCallbackStruct  passed  to  it.  After the drag procedure returns, the
                 toolkit uses the final values in  initializing  some  members  of  the  callback
                 structure   passed   to   the   appropriate  callbacks  of  the  initiator  (the
                 DragContext's        XmNdropSiteEnterCallback,         XmNdropSiteLeaveCallback,
                 XmNdragMotionCallback, or XmNoperationChangedCallback callbacks).

       XmNdropProc
                 Specifies  the  procedure  that  is  invoked  when a drop (excluding a cancel or
                 interrupt action) occurs on a drop site regardless of the  status  of  the  drop
                 site.  The  type  of  the structure whose address is passed to this procedure is
                 XmDropProcCallbackStruct. The reason sent to the procedure is XmCR_DROP_MESSAGE.

                 The  drop  procedure  may  change  the   values   of   some   members   of   the
                 XmDropProcCallbackStruct  passed  to  it.  After the drop procedure returns, the
                 toolkit  uses  the  final  values  in   initializing   some   members   of   the
                 XmDropStartCallbackStruct  passed  to  the initiator's drop start callbacks (the
                 DragContext's XmNdropStartCallback callbacks).

       XmNdropRectangles
                 Specifies a list of rectangles that describe the  shape  of  a  drop  site.  The
                 locations  of the rectangles are relative to the origin of the enclosing object.
                 When XmNdropRectangles is NULL, the drop site is assumed  to  be  the  sensitive
                 area  of the enclosing widget. If XmNdropSiteType is XmDROP_SITE_COMPOSITE, this
                 resource cannot be specified by the application.

                 Retrieving this resource returns allocated memory that needs to  be  freed  with
                 the XtFree function.

       XmNdropSiteActivity
                 Indicates   whether   a  drop  site  is  active  or  inactive.  The  values  are
                 XmDROP_SITE_ACTIVE, XmDROP_SITE_INACTIVE,  and  XmDROP_SITE_IGNORE.   An  active
                 drop  site  can  receive  a  drop,  whereas an inactive drop site is dormant. An
                 inactive drop site is treated as if it was not a registered drop  site  and  any
                 drag-under  visuals  associated  with  entering  or leaving the drop site do not
                 occur. However, it is still used for clipping drag-under effects.   A  value  of
                 XmDROP_SITE_IGNORE  indicates  that  a  drop  site  should  be  ignored  for all
                 purposes.

       XmNdropSiteOperations
                 Specifies the set of  valid  operations  associated  with  a  drop  site.   This
                 resource  is a bit mask that is formed by combining one or more of the following
                 values using  a  bitwise  operation  such  as  inclusive  OR  (|):  XmDROP_COPY,
                 XmDROP_LINK, and XmDROP_MOVE.  The value XmDROP_NOOP for this resource indicates
                 that no operations are valid.

       XmNdropSiteType
                 Specifies the type of the drop site. The possible values are

                 XmDROP_SITE_SIMPLE
                           The widget does not have any additional children that  are  registered
                           as drop sites.

                 XmDROP_SITE_COMPOSITE
                           The widget will have children that are registered as drop sites.

       XmNimportTargets
                 Specifies the list of target atoms that this drop site accepts.

       XmNnumDropRectangles
                 Specifies  the  number  of rectangles in the XmNdropRectangles list. If the drop
                 site type is XmDROP_SITE_COMPOSITE, this resource can not be  specified  by  the
                 application.

       XmNnumImportTargets
                 Specifies the number of atoms in the target atom list.

   Callback Information
       A  pointer  to  the following structure is passed to the XmNdragProc routine when the drop
       site receives crossing, motion, or operation changed messages:

       typedef struct
       {
               int reason;
               XEvent *event;
               Time timeStamp;
               Widget dragContext;
               Position x;
               Position y;
               unsigned char dropSiteStatus;
               unsigned char operation;
               unsigned char operations;
               Boolean animate;
       } XmDragProcCallbackStruct, *XmDragProcCallback;

       reason    Indicates why the callback was invoked.

       event     Points to the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the logical event.

       dragContext
                 Specifies the ID of the DragContext widget associated with the transaction.

       x         Indicates the x-coordinate of the pointer relative to the drop site.

       y         Indicates the y-coordinate of the pointer relative to the drop site.

       dropSiteStatus
                 An IN/OUT member that indicates whether or not a drop site is valid.

                 When reason is XmCR_DROP_SITE_ENTER_MESSAGE or XmCR_OPERATION_CHANGED, or reason
                 is  XmCR_DRAG_MOTION  or  XmCR_DROP_SITE_LEAVE_MESSAGE and the pointer is not in
                 the same drop site as on the previous invocation  of  the  drag  procedure,  the
                 toolkit  initializes  dropSiteStatus  to  XmDROP_SITE_VALID if the DragContext's
                 XmNexportTargets and the DropSite's XmNimportTargets are compatible and  if  the
                 initial  value  of  the  operation  member  is  not XmDROP_NOOP.  Otherwise, the
                 toolkit initializes dropSiteStatus to XmDROP_SITE_INVALID.

                 When the reason is  XmCR_DRAG_MOTION  or  XmCR_DROP_SITE_LEAVE_MESSAGE  and  the
                 pointer  is  within the same drop site as on the previous invocation of the drag
                 procedure, the toolkit initializes dropSiteStatus to the value of dropSiteStatus
                 at the time the previous invocation of the drag procedure returns.

                 The  drag  procedure  may  change  the  value  of  this  member.  After the drag
                 procedure returns,  the  toolkit  uses  the  final  value  in  initializing  the
                 dropSiteStatus member of the callback struct passed to the appropriate callbacks
                 of the initiator.

       operation An IN/OUT member that identifies an operation.

                 The toolkit initializes operation by selecting an operation from the bitwise AND
                 of  the  initial  value of the operations member and the value of the DropSite's
                 XmNdropSiteOperations  resource.   The  toolkit  searches  this  set  first  for
                 XmDROP_MOVE,  then  for  XmDROP_COPY,  then  for  XmDROP_LINK,  and  initializes
                 operation to the first operation it finds in the set.  If the toolkit finds none
                 of these operations in the set, it initializes operation to XmDROP_NOOP.

                 The  drag  procedure  may  change  the  value  of  this  member.  After the drag
                 procedure returns,  the  toolkit  uses  the  final  value  in  initializing  the
                 operation  member  of the callback struct passed to the appropriate callbacks of
                 the initiator.

       operations
                 An IN/OUT member that indicates the set of operations supported for  the  source
                 data.

                 If  the  user  does  not  select  an operation (by pressing a modifier key), the
                 toolkit   initializes   operations   to   the   value   of   the   DragContext's
                 XmNdragOperations  resource.   If the user does select an operation, the toolkit
                 initializes operations to the bitwise AND of the corresponding operation and the
                 value  of the DragContext's XmNdragOperations resource.  If the resulting set of
                 operations is empty, the toolkit initializes operations to XmDROP_NOOP.

                 The drag procedure may  change  the  value  of  this  member.   After  the  drag
                 procedure  returns,  the  toolkit  uses  the  final  value  in  initializing the
                 operations member of the callback struct passed to the appropriate callbacks  of
                 the initiator.

       animate   An OUT member that indicates whether the toolkit or the receiver client provides
                 drag-under effects for a valid drop site. If animate is set to True, the toolkit
                 provides  drop site animation per the XmNanimationStyle resource value; if it is
                 set to False, the receiver generates drag-under animation effects.

       A pointer to the following structure is passed to the XmNdropProc routine  when  the  drop
       site receives a drop message:

       typedef struct
       {
               int reason;
               XEvent *event;
               Time timeStamp;
               Widget dragContext;
               Position x;
               Position y;
               unsigned char dropSiteStatus;
               unsigned char operation;
               unsigned char operations;
               unsigned char dropAction;
       } XmDropProcCallbackStruct, *XmDropProcCallback;

       reason    Indicates why the callback was invoked.

       event     Specifies the XEvent that triggered the callback.

       timeStamp Specifies the timestamp of the logical event.

       dragContext
                 Specifies the ID of the DragContext widget associated with the transaction.

       x         Indicates the x-coordinate of the pointer relative to the drop site.

       y         Indicates the y-coordinate of the pointer relative to the drop site.

       dropSiteStatus
                 An IN/OUT member that indicates whether or not a drop site is valid.

                 The toolkit initializes dropSiteStatus to XmDROP_SITE_VALID if the DragContext's
                 XmNexportTargets and the DropSite's XmNimportTargets are compatible and  if  the
                 initial  value  of  the  operation  member  is  not XmDROP_NOOP.  Otherwise, the
                 toolkit initializes dropSiteStatus to XmDROP_SITE_INVALID.

                 The drop procedure may  change  the  value  of  this  member.   After  the  drop
                 procedure  returns,  the  toolkit  uses  the  final  value  in  initializing the
                 dropSiteStatus member of the XmDropStartCallbackStruct passed to the initiator's
                 drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

       operation An IN/OUT member that identifies an operation.

                 The toolkit initializes operation by selecting an operation from the bitwise AND
                 of the initial value of the operations member and the value  of  the  DropSite's
                 XmNdropSiteOperations  resource.   The  toolkit  searches  this  set  first  for
                 XmDROP_MOVE,  then  for  XmDROP_COPY,  then  for  XmDROP_LINK,  and  initializes
                 operation to the first operation it finds in the set.  If it finds none of these
                 operations in the set, it initializes operation to XmDROP_NOOP.

                 The drop procedure may  change  the  value  of  this  member.   After  the  drop
                 procedure  returns,  the  toolkit  uses  the  final  value  in  initializing the
                 operation member of the XmDropStartCallbackStruct passed to the initiator's drop
                 start callbacks (the DragContext's XmNdropStartCallback callbacks).

       operations
                 An  IN/OUT  member that indicates the set of operations supported for the source
                 data.

                 If the user does not select an operation  (by  pressing  a  modifier  key),  the
                 toolkit   initializes   operations   to   the   value   of   the   DragContext's
                 XmNdragOperations resource.  If the user does select an operation,  the  toolkit
                 initializes operations to the bitwise AND of the corresponding operation and the
                 value of the DragContext's XmNdragOperations resource.  If the resulting set  of
                 operations is empty, the toolkit initializes operations to XmDROP_NOOP.

                 The  drop  procedure  may  change  the  value  of  this  member.  After the drop
                 procedure returns,  the  toolkit  uses  the  final  value  in  initializing  the
                 operations  member  of  the  XmDropStartCallbackStruct passed to the initiator's
                 drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

       dropAction
                 An IN/OUT member that identifies the  action  associated  with  the  drop.   The
                 possible values are

                 XmDROP    A  drop  was  attempted.  If  the  drop  site  is valid, drop transfer
                           handling proceeds.

                 XmDROP_HELP
                           The user has requested help on the drop site.

                 The drop procedure may  change  the  value  of  this  member.   After  the  drop
                 procedure  returns,  the  toolkit  uses  the  final  value  in  initializing the
                 dropAction member of the XmDropStartCallbackStruct  passed  to  the  initiator's
                 drop start callbacks (the DragContext's XmNdropStartCallback callbacks).

RELATED INFORMATION

       XmDragContext(3),            XmDragIcon(3),           XmDropSiteConfigureStackingOrder(3),
       XmDropSiteEndUpdate(3),      XmDropSiteQueryStackingOrder(3),       XmDropSiteRegister(3),
       XmDropSiteStartUpdate(3), XmDropSiteUpdate(3), XmDropSiteUnregister(3), XmDropTransfer(3),
       and XmTargetsAreCompatible(3).

                                                                                    XmDropSite(3)