Selectable Raster Widget Documentation
---------------------------------------

The widget class for the selectable raster widget is JselRasterWidgetClass.
The include file is SelRaster.h.

The selectable raster widget dislays an image, similar to the HP static 
raster widget.  The selectable raster widget allows the user to "sweep out"
a sub-area of the image and drag it to another window.

Translations and translation behavior:
--------------------------------------

static char defaultTranslations[] =
    "<Btn1Down>:   select()\n\
     <Btn1Motion>: extend()\n\
     <Btn1Up>:     release()\n\
     <Message>:    message()"

select : If there is a swept out area and the select is inside this area,
         begin dragging.  Otherwise, call select callback and begin sweep
         of sub-area.

extend : Extend area of sweep or distance of drag, depending on last type
         of select.

release: If sweeping, end sweep and call release callback.  If dragging,
         end drag and send ClientMessage to window in which the selection
         was dropped.

message: Propogate the message to the widget parent.

Callbacks and the ClientMessage event structure are described below. 

Options: 
--------

Core options plus:

Option           Type        Usage

XtNimage         XImage *    Image to display in the widget
XtNforeground    Pixel       Foreground color for graphics context for 
                             displaying image.
XtNobjectid      Int         Sybase object id for this object.
XtNselect        Callback    See below.
XtNrelease       Callback    See below.

Callback explanations:
----------------------

Select: Is called when the user has begun selection on the widget.  
        (Default: Btn1Down) No data passed from widget for this callback.

Release: Is called when the user ends the selection process.  (Default: Btn1Up)
         The call_data for this callback is:
   
         int call_data[4];

         call_data[0] = x coordinate of selected area
         call_data[1] = y coordinate of selected area
         call_data[2] = width of selected area
         call_data[3] = height of selected area
          
         X/y coordinates are relative to the image's (0,0), and the selected
         area is guaranteed to be wholly inside the image, even when the
         image size and the widget size are different.  If the user did not
         sweep out an area on the current select, all data fields are set to
         zero.

Convenience routine:
--------------------

         Boolean JSelRasterOwnsSelection(w)
            Widget w;

         Returns True if w is a SelRaster widget and w owns the primary 
         selection, otherwise, returns False.

Selection service notes:
------------------------

         On the drag-and-drop sequence, the SelRaster widget sends a 
         ClientMessage event to the window in which the selected area was
         dropped.  The data passed with this event is:

           event.window = window to which event was sent
           event.message_type = atom named "NOTEBOOK_DROP_IMAGE"
           event.format = 32
           event.data.l[0] = time to use when requesting the selection value
           event.data.l[1] = x coordinate of drop
           event.data.l[2] = y coordinate of drop
           event.data.l[3] = window to which these coords are relative 
           event.data.l[4] = objectid 

         The receiver of this message can find contents of the swept out area 
         by requesting the value of the XA_PRIMARY selection.  The SelRaster 
         widget supports the following selection conversion targets: 

            XA_TARGETS        -- list of all targets supported
            XA_PIXMAP         -- pixmap of the selected area
            NOTEBOOK_OBJECTID -- widget's objectid

         Plus all the target types supported by the standard routine
         XmuConvertStandardSelection (currently XA_TIMESTAMP, 
         XA_HOSTNAME, XA_IP_ADDRESS, XA_USER, XA_CLASS, XA_NAME, 
         XA_CLIENT_WINDOW, XA_OWNER_OS).

Limitations:
------------

         This is never going to work on 2-headed systems if the user can drag
         the mouse from one screen to another and drop a selection, even
         if the displays have the same properties.

         The widget will display and sweep on the DEC, but does not seem to
         "hear" messages correctly when something is dropped.  After running
         this under the debugger, I have a feeling it may be a bug in the
         DEC X server--I do not have problems with the ClientMessageEvent
         on either the Sun or NCD display, using the same executable.  It does
         work on Andy's color machine, however.

         The translations must be:

              Select  :  Some button down
              Extend  :  Some button motion
              Release :  Some button up

         And all 3 must be the same button.