Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-6435881

DropTargetDragEvent.acceptDrag() documentation is unclear

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Open
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 5.0
    • Fix Version/s: None
    • Component/s: client-libs
    • Labels:
    • Subcomponent:
    • Understanding:
      Cause Known
    • CPU:
      x86
    • OS:
      windows_xp

      Description

      FULL PRODUCT VERSION :
      java version "1.5.0_06"
      Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_06-112)
      Java HotSpot(TM) Client VM (build 1.5.0_06-64, mixed mode, sharing)


      ADDITIONAL OS VERSION INFORMATION :
      (Documentation Bug: All Platforms)

      A DESCRIPTION OF THE PROBLEM :
      The documentation for DropTargetDragEvent.acceptDrag() specifies an int parameter called "dragOperation." It does not specify legal values for this int. I've searched the spec, but I can't find a definition for a "drag operation" anywhere. I can guess that what this method actually takes is a drop action, but if that is the case, the parameter should be called "drop action." The allowed drop actions are clearly specified at the beginning of the javadocs for the class, so any method parameter that requires a drop action should be called "dropAction."

      If I'm wrong in assuming "dragOperation" means "dropAction," this only clarifies my point that the documentation is unclear. If dragOperation is something else, the docs leave me with no idea what the acceptible values are.

      The description for the method also contains the phrase "... if the implementation wishes to accept an operation from the srcActions other than the one selected by the user..." which furthur clouds the issue, since it appears to be describing the drop action as an "operation," suggeting there are distinct values for a drag operation. This could also use clarification.

      Elsewhere in the DropTargetDragEvent class, the javadocs are careful to always refer to a drop action as a "drop action," which only suggests that the author has chosen the terminology carefully. But in the DragSource class, the same drop actions are referred to as "operations," without ever being clearly defined. I would appreciate it if a single term were used to describe these values, and that term were used consistently throughout the DND javadocs. But frankly, I'd be satisfied if at least this method were clarified. When I was trying to debug a problem with changing cursors as the mouse moves from one target to another, I wasted more than an hour trying to track down the definition and legal values for "drag operation."

      STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
      Read the javadocs for DropTargetDragEvent.acceptDrag().


      REPRODUCIBILITY :
      This bug can be reproduced always.

        Attachments

          Activity

            People

            Assignee:
            denis Denis Fokin (Inactive)
            Reporter:
            rmandalasunw Ranjith Mandala (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

              Dates

              Created:
              Updated:
              Imported:
              Indexed: