dragdroptut.xml

<?xml version="1.0" encoding="UTF-8"?>
<chapter id="dragdroptut">
  <title>Drag and Drop</title>

  <para>One of the more powerful features available to FOX applications is
  drag-and-drop. It's also one of the more complicated to understand. For more
  background, see the standard FOX documentation on <ulink
  url="http://www.fox-toolkit.com/draganddrop.html">Drag and
  Drop</ulink>.</para>

  <section>
    <title>Drop Sites</title>

    <para>We're going to start by presenting a skeleton application consisting
    of a main window widget (a <classname>DropSite</classname> instance) that
    parents an <classname>FXCanvas</classname> widget:</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DropSite &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drop Site", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
  end

  def create
    # Create the main window and canvas
    super

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end

if __FILE__ == $0
  FXApp.new("DropSite", "FXRuby") do |theApp|
    DropSite.new(theApp)
    theApp.create
    theApp.run
  end
end
</programlisting>

    <para>Since the main program (i.e. the part at the end) won't change for
    the rest of the tutorial, I won't show that code anymore. Since an
    <classname>FXCanvas</classname> widget relies on some other object (its
    message target) to draw its contents, we need to handle
    <constant>SEL_PAINT</constant> messages generated by the canvas. We'll do
    that by adding a handler that clears the canvas to its current background
    color:</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DropSite &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drop Site", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    
<emphasis role="bold">    # Handle expose events on the canvas
    @canvas.connect(SEL_PAINT) do |sender, sel, event|
      FXDCWindow.new(@canvas, event) do |dc|
        dc.foreground = @canvas.backColor
        dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
      end
    end</emphasis>
  end

  def create
    # Create the main window and canvas
    super

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end
</programlisting>

    <para>Run this basic version of the program to be sure that it's working
    properly so far. You should simply see an empty window with a white
    background.</para>

    <para>Now, on to the fun stuff. Our goal is to be able to drag color data
    from some other window, such as an <classname>FXColorWell</classname>
    widget, and drop it onto the canvas in order to change the canvas'
    background color. In order for a FOX widget to be able to accept drops at
    all, we need to first call its <methodname>dropEnable</methodname>
    method:</para>

    <programlisting format="linespecific">def initialize(anApp)
  # Initialize base class
  super(anApp, "Drop Site", :opts => DECOR_ALL, :width => 400, :height => 300)
  
  # Fill main window with canvas
  @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    
  # Handle expose events on the canvas
  @canvas.connect(SEL_PAINT) do |sender, sel, event|
    FXDCWindow.new(@canvas, event) do |dc|
      dc.foreground = @canvas.backColor
      dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
    end
  end

<emphasis role="bold">  # Enable canvas for drag-and-drop messages
  @canvas.dropEnable
</emphasis>end
</programlisting>

    <para>At this point, let's try a little test to see if the program does
    anything interesting yet. Start by running some other FOX or FXRuby
    program to use as a drag source for the color data. You should be able to
    use any program that displays an FXColorWell widget, and this includes the
    standard color dialog box shown here:</para>

    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="images/colordialog.png"
                     format="PNG" />
        </imageobject>
      </mediaobject>
    </screenshot>

    <para>Each of the small colored boxes near the bottom of the color dialog
    box are color wells, and the large box on the left-hand side of the color
    dialog box is also a color well. Now start your drag-and-drop test program
    and try to drag a color from one of these color wells onto this window. At
    this point, the mouse pointer should turn into a stop sign, indicating
    that the canvas isn't accepting drops of color data yet.</para>

    <para>To correct this problem, we need to use the canvas'
    <methodname>acceptDrop</methodname> method to indicate whether or not
    we'll accept certain kinds of drops. You can call
    <methodname>acceptDrop</methodname> any time after receiving the initial
    <constant>SEL_DND_ENTER</constant> message, but it's usually done in
    response to a <constant>SEL_DND_MOTION</constant> message. Let's add a
    handler for <constant>SEL_DND_MOTION</constant> messages from the canvas
    in DropSite's <methodname>initialize</methodname> method. For now, we'll unconditionally accept
    drops from any drag source, regardless of what kind of data they're
    offering:</para>

    <programlisting format="linespecific">def initialize(anApp)
  # Initialize base class
  super(anApp, "Drop Site", :opts => DECOR_ALL, :width => 400, :height => 300)
    
  # Fill main window with canvas
  @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    
  # Handle expose events on the canvas
  @canvas.connect(SEL_PAINT) do |sender, sel, event|
    FXDCWindow.new(@canvas, event) do |dc|
      dc.foreground = @canvas.backColor
      dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
    end
  end

  # Enable canvas for drag-and-drop messages
  @canvas.dropEnable
  
<emphasis role="bold">  # Handle SEL_DND_MOTION messages from the canvas
  @canvas.connect(SEL_DND_MOTION) do
    # Accept drops unconditionally (for now)
    @canvas.acceptDrop
  end
</emphasis>end
</programlisting>

    <para>Now try the previous test again. This time, when you try to drag
    from a color well to the drop-enabled canvas, you should see the mouse
    pointer turn into a small filled square. This is a visual cue to the user
    indicating that the canvas will accept a drop of the drag-and-drop
    data.</para>

    <para>Now it's time to get more specific about what kind of data is being
    dragged between these applications, and how to process that data. So far,
    our drop-enabled canvas merely knows that you're dragging some kind of
    data from a drag source, but it doesn't know what kind of data it is. We
    really need to be more exclusive about what kinds of data are acceptable.
    FOX uses unique drag types to distinguish between different kinds of
    "draggable" data. As you'll see later, you have the freedom to define drag
    types for any kind of application-specific data that you need; but for
    now, we're going to use FOX's built-in drag type for color data.</para>

    <para>Drag types (even the standard ones) must be registered before they
    can be used, and so we'll start by adding a few lines to
    <classname>DropSite</classname>'s <methodname>create</methodname> method
    to register the drag type for color data:</para>

    <programlisting format="linespecific">def create
  # Create the main window and canvas
  super
  
<emphasis role="bold">  # Register the drag type for colors
  FXWindow.colorType = getApp().registerDragType(FXWindow.colorTypeName)

</emphasis>  # Show the main window
  show(PLACEMENT_SCREEN)
end
</programlisting>

    <para>Note that the first time that
    <methodname>registerDragType</methodname> is called for a particular
    drag type name (such as <methodname>FXWindow.colorTypeName</methodname>)
    it will generate a unique identifier for that drag type. Subsequent calls
    to <methodname>registerDragType</methodname> for the same drag type name
    will just return the previously-generated drag type. Now, we want to
    modify our <constant>SEL_DND_MOTION</constant> handler so that it's a
    little more picky about which kinds of drops it will accept:</para>

    <programlisting format="linespecific"># Handle SEL_DND_MOTION messages from the canvas
@canvas.connect(SEL_DND_MOTION) do
<emphasis role="bold">  if @canvas.offeredDNDType?(FROM_DRAGNDROP, FXWindow.colorType)
    @canvas.acceptDrop
  end
</emphasis>end
</programlisting>

    <para>Here, we call the canvas' <methodname>offeredDNDType?</methodname>
    method to ask if the drag source can provide its data in the requested
    format. Only if <methodname>offeredDNDType?</methodname> returns true will
    we call <methodname>acceptDrop</methodname> as before.</para>

    <para>The last step is to actually handle the drop, and for that we add a
    handler for the <constant>SEL_DND_DROP</constant> message:</para>

    <programlisting format="linespecific"><emphasis role="bold"># Handle SEL_DND_DROP message from the canvas
@canvas.connect(SEL_DND_DROP) do
  # Try to obtain the data as color values first
  data = @canvas.getDNDData(FROM_DRAGNDROP, FXWindow.colorType)
  unless data.nil?
    # Update canvas background color
    @canvas.backColor = Fox.fxdecodeColorData(data)
  end
end</emphasis></programlisting>

    <para>Assuming that the drag source is able to provide its data in the
    requested format, the <methodname>getDNDData</methodname> method will
    return a string (which for our purposes is just a byte buffer). If you've
    defined your own application-specific drag types, this data can of course
    be anything, and we'll see examples of this in a later tutorial. But the
    data for standard drag types like
    <methodname>FXWindow.colorType</methodname> can be decoded using the
    appropriate built-in library functions. In this case, we use the
    <methodname>fxdecodeColorData</methodname> method to convert the bytes
    into a color value that we can use.</para>

    <para>Now comes the moment of truth. Try running your test program again
    (one that displays a color well). Now, when you drag a color from a color
    well and drop it onto the <classname>DropSite</classname> window, the
    canvas should change its background color accordingly.</para>

    <para>The complete program is listed below, and is included in the
    <filename class="directory">examples</filename> directory under the file
    name <filename>dropsite.rb</filename>.</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DropSite &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drop Site", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    
    # Handle expose events on the canvas
    @canvas.connect(SEL_PAINT) do |sender, sel, event|
      FXDCWindow.new(@canvas, event) do |dc|
        dc.foreground = @canvas.backColor
        dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
      end
    end

    # Enable canvas for drag-and-drop messages
    @canvas.dropEnable
    
    # Handle SEL_DND_MOTION messages from the canvas
    @canvas.connect(SEL_DND_MOTION) do
      if @canvas.offeredDNDType?(FROM_DRAGNDROP, FXWindow.colorType)
        @canvas.acceptDrop
      end
    end

    # Handle SEL_DND_DROP message from the canvas
    @canvas.connect(SEL_DND_DROP) do
      # Try to obtain the data as color values first
      data = @canvas.getDNDData(FROM_DRAGNDROP, FXWindow.colorType)
      unless data.nil?
        # Update canvas background color
        @canvas.backColor = Fox.fxdecodeColorData(data)
      end
    end
  end

  def create
    # Create the main window and canvas
    super
    
    # Register the drag type for colors
    FXWindow.colorType = getApp().registerDragType(FXWindow.colorTypeName)

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end

if __FILE__ == $0
  FXApp.new("DropSite", "FXRuby") do |theApp|
    DropSite.new(theApp)
    theApp.create
    theApp.run
  end
end
</programlisting>
  </section>

  <section>
    <title>Drag Sources</title>

    <para>As before, we're going to start by presenting a skeleton application
    consisting of a main window widget (a <classname>DragSource</classname>
    instance) that parents an <classname>FXCanvas</classname> widget:</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DragSource &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drag Source", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    @canvas.backColor = "red"
    
    # Handle expose events on the canvas
    @canvas.connect(SEL_PAINT) do |sender, sel, event|
      FXDCWindow.new(@canvas, event) do |dc|
        dc.foreground = @canvas.backColor
        dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
      end
    end
  end

  def create
    # Create the main window and canvas
    super
    
    # Register the drag type for colors
    FXWindow.colorType = getApp().registerDragType(FXWindow.colorTypeName)

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end

if __FILE__ == $0
  FXApp.new("DragSource", "FXRuby") do |theApp|
    DragSource.new(theApp)
    theApp.create
    theApp.run
  end
end

</programlisting>

    <para>Since the main program (i.e. the part at the end) won't change for
    the rest of the tutorial, I won't show that code anymore. Furthermore, the
    <classname>DragSource</classname> class has a few things in common with
    the <classname>DropSite</classname> class from the previous example,
    namely:</para>

    <itemizedlist>
      <listitem>
        <para>We've defined a <constant>SEL_PAINT</constant> handler for the
        canvas widget that just clears the canvas to its current background
        color; and,</para>
      </listitem>

      <listitem>
        <para>The drag type for colors
        (<constant>FXWindow.colorType</constant>) is registered in the
        <classname>DragSource</classname>'s <methodname>create</methodname>
        method.</para>
      </listitem>
    </itemizedlist>

    <para>As before, you may want to run this basic version of the program to
    be sure that it's working properly so far. You should simply see an empty
    window with a red background.</para>

    <para>Now for this application, we want a drag operation to begin when the
    user presses the left mouse button inside the canvas and starts "dragging"
    away from the canvas. So the first change we need to make is to add a
    handler for the <constant>SEL_LEFTBUTTONPRESS</constant> message from the
    canvas:</para>

    <programlisting format="linespecific">@canvas.connect(SEL_LEFTBUTTONPRESS) do
  #
  # Capture (grab) the mouse when the button goes down, so that all future
  # mouse events will be reported to this widget, even if those events occur
  # outside of this widget.
  #
  @canvas.grab

  # Advertise which drag types we can offer
  dragTypes = [FXWindow.colorType]
  @canvas.beginDrag(dragTypes)
end
</programlisting>

    <para>Note that there are usually two things you're going to want to do in
    the <constant>SEL_LEFTBUTTONPRESS</constant> handler for a drag source.
    The first is to call <methodname>grab</methodname> on the window that
    acts as the drag source. Calling <methodname>grab</methodname>
    "captures" the mouse in the sense that subsequent mouse motion events will
    be reported as if they occurred inside the grab window. This is important,
    since in our case we're going to be dragging from this window to some
    other window, possibly a window in a different application
    altogether.</para>

    <para>The second thing you'll want to do in the
    <constant>SEL_LEFTBUTTONPRESS</constant> handler for a drag source is to
    call <methodname>beginDrag</methodname>. This not only kicks the
    application into drag-and-drop mode, but also provides a way for you to
    inform the system about the formats of data (i.e. the drag types) that
    this drag source is able to provide. For this example, the drag source is
    just going to offer one drag type.</para>

    <para>Since releasing the left mouse button should end the drag operation,
    it's important to also add a handler for the
    <constant>SEL_LEFTBUTTONRELEASE</constant> message:</para>

    <programlisting format="linespecific">@canvas.connect(SEL_LEFTBUTTONRELEASE) do
  @canvas.ungrab
  @canvas.endDrag
end
</programlisting>

    <para>This is pretty much the mirror image of our
    <constant>SEL_LEFTBUTTONPRESS</constant> handler. We call
    <methodname>ungrab</methodname> to release the mouse capture, and
    <methodname>endDrag</methodname> to clean up the drag-and-drop
    state.</para>

    <para>The next change is to add a <constant>SEL_MOTION</constant> handler,
    to handle mouse motion events during the drag operation:</para>

    <programlisting format="linespecific">@canvas.connect(SEL_MOTION) do |sender, sel, event|
  if @canvas.dragging?
    @canvas.handleDrag(event.root_x, event.root_y)
    unless @canvas.didAccept == DRAG_REJECT
      @canvas.dragCursor = getApp().getDefaultCursor(DEF_SWATCH_CURSOR)
    else
      @canvas.dragCursor = getApp().getDefaultCursor(DEF_DNDSTOP_CURSOR)
    end
  end
end
</programlisting>

    <para>The <methodname>dragging?</methodname> method returns true if we're
    in the middle of a drag-and-drop operation for the drag source window,
    i.e. after the call to <methodname>beginDrag</methodname> but before the
    call to <methodname>endDrag</methodname>. If we're not currently
    processing a drag operation, we're not really interested in mouse motion
    events for the canvas.</para>

    <para>If we <emphasis>are</emphasis> processing a drag operation, however,
    we need to call <methodname>handleDrag</methodname> on the drag source
    window. FOX uses this information to send drag-and-drop messages (such as
    <constant>SEL_DND_ENTER</constant>, <constant>SEL_DND_MOTION</constant>
    and <constant>SEL_DND_LEAVE</constant>) to the window that the mouse is
    currently over. Note that the coordinates passed to
    <methodname>handleDrag</methodname> are root window coordinates, and not
    window-local coordinates.</para>

    <para>Another good thing to consider doing here is to change the shape of
    the cursor depending on the drop site's response to the drag-and-drop
    messages from the drag source. For this example, we change the drag cursor
    to one of FOX's built-in cursor shapes
    (<constant>DEF_SWATCH_CURSOR</constant>) if we get any response other than
    <constant>DRAG_REJECT</constant> from the drop site. If the drop site
    rejects this drag source's overtures, we instead change the drag cursor to
    a cursor that resembles a stop sign
    (<constant>DEF_DNDSTOP_CURSOR</constant>).</para>

    <para>I've purposely avoided suggesting that you run the program for the
    last couple of changes, since until now there wasn't going to be any
    visual indication that anything interesting was happening. But now you
    should be able to run the application in its current state and see a few
    things.</para>

    <para>A first test is to confirm that the cursor shape changes to the
    "stop" sign when you attempt to drag over some window that isn't willing
    to accept a drop of the <constant>FXWindow.colorType</constant> drag type.
    Start up one of the other FXRuby example programs (such as the
    <filename>scribble.rb</filename> example) alongside your drag source
    program, and then try "dragging" from the drag source's canvas onto the
    Scribble program's canvas. During the drag attempt, the cursor should
    maintain its shape as a "stop" sign since the canvas in the
    <filename>scribble.rb</filename> example isn't drop-enabled.</para>

    <para>Your next test can confirm that the cursor shape changes to the
    "swatch" cursor (a small square) when you attempt to drag over a window
    that is drop-enabled, and which is willing to accepts drops of this drag
    type. The obvious choice is the example from the previous section (the
    dropsite.rb program), but you should have success with any FXRuby example
    program that displays color wells. Start up one of these drop-enabled
    programs alongside your drag source program, and then try "dragging" from
    the drag source's canvas onto the drop site. While the mouse pointer is
    over a drop-enabled window, the cursor should change its shape.</para>

    <para>The last (and most important) step is to actually complete the data
    transfer. At any time during a drag-and-drop operation, a drop site may
    request a copy of the drag-and-drop data by calling the
    <methodname>getDNDData</methodname> method (as described in the previous
    section). When this happens, FOX sends a
    <constant>SEL_DND_REQUEST</constant> message to the current drag source
    window, and so we now add a handler for that message:</para>

    <programlisting format="linespecific">@canvas.connect(SEL_DND_REQUEST) do |sender, sel, event|
  if event.target == FXWindow.colorType
    @canvas.setDNDData(FROM_DRAGNDROP, FXWindow.colorType, Fox.fxencodeColorData(@canvas.backColor))
  end
end
</programlisting>

    <para>The first important thing to note here is that the
    <varname>target</varname> field of the <classname>FXEvent</classname>
    instance will contain the drag type requested by the drop site. If your
    drag source offers its data in multiple formats, you definitely need to
    check this in order to know how to package-up the data for transfer.
    However, even if you're only offering the data in a single format (as in
    this example) it's still a good idea to check the requested type, since a
    rogue drop site could ask for the data in some unexpected format.</para>

    <para>Assuming that the drag type is as expected, the last step is send
    the data to the drop site by calling
    <methodname>setDNDData</methodname>. As with the call to
    <methodname>getDNDData</methodname> for our previous drop site program,
    you want to be sure to specify the origin of the data
    (<constant>FROM_DRAGNDROP</constant>), the drag type
    (<constant>FXWindow.colorType</constant>) and the data itself as a binary
    string.</para>

    <para>As a final test of the completed program, try dragging from this
    window to some drop-enabled window (as described earlier). Now, when you
    release the left mouse button to complete the "drop", the drop site should
    change its color to red.</para>

    <para>The complete program is listed below, and is included in the
    <filename class="directory">examples</filename> directory under the file
    name <filename>dragsource.rb</filename>.</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DragSource &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drag Source", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    @canvas.backColor = "red"
    
    # Handle expose events on the canvas
    @canvas.connect(SEL_PAINT) do |sender, sel, event|
      FXDCWindow.new(@canvas, event) do |dc|
        dc.foreground = @canvas.backColor
        dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
      end
    end

    # Handle left button press
    @canvas.connect(SEL_LEFTBUTTONPRESS) do
      #
      # Capture (grab) the mouse when the button goes down, so that all future
      # mouse events will be reported to this widget, even if those events occur
      # outside of this widget.
      #
      @canvas.grab

      # Advertise which drag types we can offer
      dragTypes = [FXWindow.colorType]
      @canvas.beginDrag(dragTypes)
    end
    
    # Handle mouse motion events
    @canvas.connect(SEL_MOTION) do |sender, sel, event|
      if @canvas.dragging?
        @canvas.handleDrag(event.root_x, event.root_y)
        unless @canvas.didAccept == DRAG_REJECT
          @canvas.dragCursor = getApp().getDefaultCursor(DEF_SWATCH_CURSOR)
        else
          @canvas.dragCursor = getApp().getDefaultCursor(DEF_DNDSTOP_CURSOR)
        end
      end
    end

    # Handle left button release
    @canvas.connect(SEL_LEFTBUTTONRELEASE) do
      @canvas.ungrab
      @canvas.endDrag
    end
    
    # Handle request for DND data
    @canvas.connect(SEL_DND_REQUEST) do |sender, sel, event|
      if event.target == FXWindow.colorType
        @canvas.setDNDData(FROM_DRAGNDROP, FXWindow.colorType, Fox.fxencodeColorData(@canvas.backColor))
      end
    end
  end

  def create
    # Create the main window and canvas
    super
    
    # Register the drag type for colors
    FXWindow.colorType = getApp().registerDragType(FXWindow.colorTypeName)

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end

if __FILE__ == $0
  FXApp.new("DragSource", "FXRuby") do |theApp|
    DragSource.new(theApp)
    theApp.create
    theApp.run
  end
end

</programlisting>
  </section>

  <section>
    <title>Putting It All Together</title>

    <para>We've studied drag-and-drop enabled applications from two points of
    view, that of a drag source and that of a drop site. But for most
    applications, you'll want a window to act as both a drag source
    <emphasis>and</emphasis> a drop site. As it turns out, this is just a
    simple combination of the techniques we've already seen in the previous
    sections.</para>

    <para>If we use our completed drag source example program from the
    previous section as a starting point, and then compare it to the drop site
    example from the first section, it is apparent that the only "pieces"
    missing are:</para>

    <itemizedlist>
      <listitem>
        <para>A call to <methodname>dropEnable</methodname>, to make
        <classname>DragSource</classname>'s canvas drop-enabled;</para>
      </listitem>

      <listitem>
        <para>A handler for the <constant>SEL_DND_MOTION</constant> message;
        and,</para>
      </listitem>

      <listitem>
        <para>A handler for the <constant>SEL_DND_DROP</constant>
        message.</para>
      </listitem>
    </itemizedlist>

    <para>If you merge those three short bits of code from
    <filename>dropsite.rb</filename> into <filename>dragsource.rb</filename>,
    you should end up with a program that can act as both a drag source and a
    drop site. To test this program, you should be able to start up two
    separate copies side-by-side and then drag from one to the other. Since,
    as written, both copies will start up with a red background, you might
    want to modify one of them to have a different initial backgroud color.
    Another interesting possibility is to start up a third program (such as an
    FXRuby example that has displays a color dialog) and drag colors back and
    forth between all three programs. You could spend days doing this and
    never leave the house.</para>

    <para>The complete program is listed below, and is included in the
    <filename class="directory">examples</filename> directory under the file
    name <filename>dragdrop.rb</filename>.</para>

    <programlisting format="linespecific">require 'fox16'

include Fox

class DragDropWindow &lt; FXMainWindow
  def initialize(anApp)
    # Initialize base class
    super(anApp, "Drag and Drop", :opts => DECOR_ALL, :width => 400, :height => 300)
    
    # Fill main window with canvas
    @canvas = FXCanvas.new(self, :opts => LAYOUT_FILL_X|LAYOUT_FILL_Y)
    @canvas.backColor = "red"
    
    # Enable canvas for drag-and-drop messages
    @canvas.dropEnable
    
    # Handle expose events on the canvas
    @canvas.connect(SEL_PAINT) do |sender, sel, event|
      FXDCWindow.new(@canvas, event) do |dc|
        dc.foreground = @canvas.backColor
        dc.fillRectangle(event.rect.x, event.rect.y, event.rect.w, event.rect.h)
      end
    end

    # Handle left button press
    @canvas.connect(SEL_LEFTBUTTONPRESS) do
      #
      # Capture (grab) the mouse when the button goes down, so that all future
      # mouse events will be reported to this widget, even if those events occur
      # outside of this widget.
      #
      @canvas.grab

      # Advertise which drag types we can offer
      dragTypes = [FXWindow.colorType]
      @canvas.beginDrag(dragTypes)
    end
    
    # Handle mouse motion events
    @canvas.connect(SEL_MOTION) do |sender, sel, event|
      if @canvas.dragging?
        @canvas.handleDrag(event.root_x, event.root_y)
        unless @canvas.didAccept == DRAG_REJECT
          @canvas.dragCursor = getApp().getDefaultCursor(DEF_SWATCH_CURSOR)
        else
          @canvas.dragCursor = getApp().getDefaultCursor(DEF_DNDSTOP_CURSOR)
        end
      end
    end

    # Handle SEL_DND_MOTION messages from the canvas
    @canvas.connect(SEL_DND_MOTION) do
      if @canvas.offeredDNDType?(FROM_DRAGNDROP, FXWindow.colorType)
        @canvas.acceptDrop
      end
    end

    # Handle left button release
    @canvas.connect(SEL_LEFTBUTTONRELEASE) do
      @canvas.ungrab
      @canvas.endDrag
    end
    
    # Handle SEL_DND_DROP message from the canvas
    @canvas.connect(SEL_DND_DROP) do
      # Try to obtain the data as color values first
      data = @canvas.getDNDData(FROM_DRAGNDROP, FXWindow.colorType)
      unless data.nil?
        # Update canvas background color
        @canvas.backColor = Fox.fxdecodeColorData(data)
      end
    end

    # Handle request for DND data
    @canvas.connect(SEL_DND_REQUEST) do |sender, sel, event|
      if event.target == FXWindow.colorType
        @canvas.setDNDData(FROM_DRAGNDROP, FXWindow.colorType, Fox.fxencodeColorData(@canvas.backColor))
      end
    end
  end

  def create
    # Create the main window and canvas
    super
    
    # Register the drag type for colors
    FXWindow.colorType = getApp().registerDragType(FXWindow.colorTypeName)

    # Show the main window
    show(PLACEMENT_SCREEN)
  end
end

if __FILE__ == $0
  FXApp.new("DragDrop", "FXRuby") do |theApp|
    DragDropWindow.new(theApp)
    theApp.create
    theApp.run
  end
end

</programlisting>
  </section>
</chapter>