Technical Note TN1043

On Drag Manager Additions (Release 1.1)

Note:
If you're looking at this document in black and white, you'll have to imagine the lower right image to be opaque as normal and the upper left image to be somewhat less visually substantial -- in a word, translucent.

Important:
While the Drag Manager will not allow translucency when the environment does not permit it, such as on 8-bit monitors with altered color tables, it can't prevent translucency from being used when it is inappropriate. Design your program to use translucent dragging only when it's appropriate. Consider following the example of the Finder and combining dragging of a small image with outlines for other items in the drag.

typedef unsigned long DragImageFlags;

enum
{
    dragStandardImage            = 0x00000000,
    dragDarkImage                = 0x00000001,
    dragDarkerImage                = 0x00000002,
    dragOpaqueImage                = 0x00000003,
    dragRegionAndImage            = 0x00000010
};

pascal OSErr SetDragImage (    DragReference    theDragRef,
                PixMapHandle    imagePixMap,
                RgnHandle    imageRgn,
                Point    imageOffsetPt,
                DragImageFlags    theImageFlags    );


imagePixMap    A standard PixMapHandle. The Drag Manager will
        temporarily lock the PixMapHandle during the drag
        if necessary. Not copied into the DragReference. See below.
imageRgn    A mask for the PixMap describing the portion of
        the PixMap which contains the image. Pass nil for
        imageRgn if the entire rectangular PixMap, including
        white space, is to be dragged. Not copied into the DragReference. See below.

imageOffsetPt    The offset required to move the imagePixMap to the
        global coordinates where the image initially appears.
        If imageOffsetPt is {0,0}, the imagePixMap should
        already be in global coordinates.
theImageFlags    A set of drag image flags as described above.

enum
{
    unsupportedForPlatformErr = -1858,
        // call is for PowerPC only
    noSuitableDisplaysErr = -1859,
        // no displays support translucency
    badImageRgnErr = -1860,
        // bad translucent image region
    badImageErr = -1861
        // bad translucent image PixMap
};

#pragma once

#ifndef __DRAG__
#   include <Drag.h>
#endif

enum
{
    _DragDispatch = 0xABED
};

enum
{
    gestaltDragMgrHasImageSupport = 3
};

enum
{
    unsupportedForPlatformErr   = -1858,
        // call is for PowerPC only
    noSuitableDisplaysErr       = -1859,
        // no displays support translucency
    badImageRgnErr              = -1860,
        // bad translucent image region
    badImageErr                 = -1861
        // bad translucent image PixMap
};

typedef unsigned long DragImageFlags;

enum
{
    dragStandardImage   = 0x00000000,
    dragDarkImage       = 0x00000001,
    dragDarkerImage     = 0x00000002,
    dragOpaqueImage     = 0x00000003,
    dragRegionAndImage  = 0x00000010
};

#ifdef __cplusplus
extern "C" {
#endif

pascal OSErr SetDragImage ( DragReference   theDragRef,
                            PixMapHandle    imagePixMap,
                            RgnHandle       imageRgn,
                            Point           imageOffsetPt,
                            DragImageFlags  theImageFlags   )
    TWOWORDINLINE (0x7027, 0xABED);

pascal OSErr GetDragHiliteColor
    (WindowPtr window, RGBColor *color)
        TWOWORDINLINE (0x7026, 0xABED);

#ifdef __cplusplus
}
#endif

#define SystemSevenFiveOrLater  1
#define CGLUESUPPORTED          0
#define OLDROUTINENAMES         0
#define OLDROUTINELOCATIONS     0
#define STRICT_WINDOWS          1

#ifndef __CONDITIONALMACROS__
#   include <ConditionalMacros.h>
#endif

#if GENERATINGCFM

    //
    // If we're not generating CFM, then assume the
    // 68K inlines in the headers apply instead.
    //

#include "DragManagerAdditions.h"
    // if missing, see Appendix A1, Technote 1043

pascal OSErr SetDragImage ( DragReference   theDragRef,
                            PixMapHandle    imagePixMap,
                            RgnHandle       imageRgn,
                            Point           imageOffsetPt,
                            DragImageFlags  theImageFlags   )
{
    enum
    {
        uppSetDragImageInfo = kD0DispatchedPascalStackBased
            | RESULT_SIZE (SIZE_CODE (sizeof(OSErr)))
            | DISPATCHED_STACK_ROUTINE_SELECTOR_SIZE
                  (SIZE_CODE (sizeof (unsigned long)))
            | DISPATCHED_STACK_ROUTINE_PARAMETER
                  (1, SIZE_CODE (sizeof (theDragRef)))
            | DISPATCHED_STACK_ROUTINE_PARAMETER
                  (2, SIZE_CODE (sizeof (imagePixMap)))
            | DISPATCHED_STACK_ROUTINE_PARAMETER
                  (3, SIZE_CODE (sizeof (imageRgn)))
            | DISPATCHED_STACK_ROUTINE_PARAMETER
                  (4, SIZE_CODE (sizeof (imageOffsetPt)))
            | DISPATCHED_STACK_ROUTINE_PARAMETER
                  (5, SIZE_CODE (sizeof (theImageFlags)))
    };

    return CallUniversalProc (
        GetToolTrapAddress (_DragDispatch),
        uppSetDragImageInfo, 0x27L, theDragRef, imagePixMap,
        imageRgn, imageOffsetPt, theImageFlags);
}

pascal OSErr GetDragHiliteColor (WindowPtr window, RGBColor *color)
{
    enum
    {
        uppGetDragHiliteColorInfo =
            kD0DispatchedPascalStackBased
                | RESULT_SIZE (SIZE_CODE (sizeof(OSErr)))
                | DISPATCHED_STACK_ROUTINE_SELECTOR_SIZE
                    (SIZE_CODE (sizeof (unsigned long)))
                | DISPATCHED_STACK_ROUTINE_PARAMETER
                    (1, SIZE_CODE (sizeof (window)))
                | DISPATCHED_STACK_ROUTINE_PARAMETER
                    (2, SIZE_CODE (sizeof (color)))
    };

    return CallUniversalProc (
        GetToolTrapAddress (_DragDispatch),
            uppGetDragHiliteColorInfo, 0x26L, window, color);
}

#endif // GENERATINGCFM

#ifndef __QDOFFSCREEN__
#   include <QDOffscreen.h>
#endif

#ifndef __GESTALT__
#   include <Gestalt.h>
#endif

#ifndef __EVENTS__
#   include <Events.h>
#endif

#ifndef __WINDOWS__
#   include <Windows.h>
#endif

#ifndef __QUICKDRAW__
#   include <QuickDraw.h>
#endif

#include "TranslucentDragSample.h"
    // just a prototype for MyDoPictureDrag
#include "DragManagerAdditions.h"
    // if missing, see Appendix A1, Technote 1043

pascal OSErr MyDoPictureDrag (  const EventRecord   *theEvent,
                                WindowPtr           theWindow,
                                PicHandle           thePicture  )
{
    OSErr               err;
    DragReference       theDrag;
    GWorldPtr           imageGWorld;
    PixMapHandle        imagePixMap;
    Rect                imageRect;
    Rect                dragBounds;
    RgnHandle           dragRgn;
    RgnHandle           tempRgn;
    RgnHandle           imageRgn;
    RgnHandle           contRgn;
    ItemReference       theItem;
    char                saveHState;
    long                response;
    CGrafPtr            savePort;
    Point               offsetPt;
    GDHandle            saveDevice;

    //
    //  initialize values to allow for safe and easy
    //  clean-up
    //

    theDrag         = 0;
    imageGWorld     = nil;
    dragRgn         = nil;
    tempRgn         = nil;
    imageRgn        = nil;
    contRgn         = nil;

    GetGWorld(&savePort, &saveDevice);

    //
    //  create a new drag
    //

    err = NewDrag(&theDrag);
    if (err != noErr) goto Bail;

    //
    //  add the picture data to the drag
    //

    saveHState = HGetState((Handle) thePicture);
    HLock ((Handle) thePicture);

    theItem = 1;
    err = AddDragItemFlavor(theDrag, theItem, 'PICT',
        *thePicture, GetHandleSize((Handle) thePicture), 0);
    HSetState ((Handle) thePicture, saveHState);
    if (err != noErr) goto Bail;

    //
    //  get the bounding rect of the picture and relocate
    //  it to 0,0
    //

    imageRect = (**thePicture).picFrame;
    SetPt (&offsetPt, imageRect.left, imageRect.top);
    OffsetRect (&imageRect, -imageRect.left, -imageRect.top);

    //
    //  since our imageRect is based at 0,0, find
    //  the global offset of the image
    //

    SetPort (theWindow);
    LocalToGlobal (&offsetPt);
    SetPort ((GrafPtr) savePort);

    //
    //  check if the Drag Manager supports image dragging
    //

    err = Gestalt(gestaltDragMgrAttr, &response);
    if (err == noErr && (response & (1L << gestaltDragMgrHasImageSupport)))
    {
        //
        //  allocate a GWorld to hold the image; it is
        //  okay if the pixels are in the app heap or
        //  in temp memory
        //

        err = NewGWorld
            (&imageGWorld, 8, &imageRect, nil, nil, useTempMem);
        if (err)
            err = NewGWorld (&imageGWorld, 8, &imageRect, nil, nil, 0);

        if (err == noErr)
        {
            //
            //  get the pixel map from the GWorld for:
            //
            //      [1] LockPixels before drawing
            //      [2] SetDragImage
            //

            imagePixMap = GetGWorldPixMap(imageGWorld);

            //  draw the picture into the GWorld

            SetGWorld(imageGWorld, nil);
            (void) LockPixels(imagePixMap);
                //  LockPixels always returns true for
                //  non-purgeable pixels
            EraseRect (&imageGWorld->portRect);
            DrawPicture(thePicture, &imageRect;));
            UnlockPixels(imagePixMap);
            SetGWorld(savePort, saveDevice);

            //
            //  allocate and set the region that
            //  identifies the part of the image
            //  being dragged
            //

            imageRgn = NewRgn();
            if (imageRgn == nil)
                err = MemError ( );
            else
            {
                RectRgn (imageRgn, &imageRect);

                //  attach the image to the drag

                err = SetDragImage (theDrag, imagePixMap, imageRgn,
                    offsetPt, dragStandardImage);
            }
        }

        //
        //  Translucency is not critical, so errors which
        //  occur during any of the enclosed code are not fatal;
        //  we've only bothered to assign 'err' to see its value
        //  in the debugger.
        //

        err = noErr;
    }

    //
    //  set the bounds and region for the drag using the
    //  window's content rectangle and the imageRect in
    //  its global location
    //

    dragBounds = imageRect;
    OffsetRect(&dragBounds, offsetPt.h, offsetPt.v);

    contRgn = NewRgn ( );
    if (contRgn == nil)
    {
        err = MemError ( );
        goto Bail;
    }

    GetWindowContentRgn (theWindow,contRgn);
    SectRect (&((**contRgn).rgnBBox), &dragBounds, &dragBounds);
    err = SetDragItemBounds(theDrag, theItem, &dragBounds);
    if (err != noErr) goto Bail;

    //
    //  make a drag region outlining the image for screens
    //  on which translucency isn't possible
    //

    dragRgn = NewRgn();
    if (dragRgn == nil)
    {
        err = MemError ( );
        goto Bail;
    }

    RectRgn(dragRgn, &dragBounds);

    tempRgn = NewRgn();
    if (tempRgn == nil)
    {
        err = MemError ( );
        goto Bail;
    }

    CopyRgn(dragRgn, tempRgn);
    InsetRgn(tempRgn, 1, 1);
    DiffRgn(dragRgn, tempRgn, dragRgn);

    //
    //  finally, do the drag
    //

    err = TrackDrag(theDrag, theEvent, dragRgn);

Bail:

    if (theDrag)(void)  DisposeDrag     (theDrag);
    if (imageGWorld)    DisposeGWorld   (imageGWorld);
    if (dragRgn)        DisposeRgn      (dragRgn);
    if (tempRgn)        DisposeRgn      (tempRgn);
    if (imageRgn)       DisposeRgn      (imageRgn);
    if (contRgn)        DisposeRgn      (contRgn);

    return err;
}