Class NativeDropEvent

java.lang.Object
com.codename1.ui.events.ActionEvent
com.codename1.ui.NativeDropEvent
public final class NativeDropEvent extends ActionEvent

One step of a native operating system drag passing over, or landing on, a component that was marked as a native drop target with Component#setNativeDropTarget(boolean).

The payload is a ClipboardContent -- the same shape a paste produces -- so a component that already knows how to paste knows how to accept a drop. Inspect ClipboardContent#getMimeTypes() and take the richest representation you understand, exactly as you would for a paste.

The x and y inherited from ActionEvent are absolute screen coordinates within the surface the drag is over, so Component#getAbsoluteX() and Component#getAbsoluteY() convert them to component coordinates.

Accepting

A drag event tells the operating system whether the drop would be allowed and what would happen. Call #accept(int) with one of the actions in #getAllowedActions() to show the user the corresponding cursor, or #reject() to refuse. A target that never calls either accepts NativeDragOperation#ACTION_COPY when the source allows it, which is what most targets want.

  • Method Details

    • getContent

      public ClipboardContent getContent()

      Returns the dragged payload.

      Read from it while handling the drop. See Component#nativeDrop(com.codename1.ui.NativeDropEvent) for what a representation may be backed by, and for how long.

    • getTarget

      public Component getTarget()
      Returns the component the drag is over.

    • getAllowedActions

      public int getAllowedActions()

      Returns the bit set of actions that may be agreed to here and now, which is what #accept(int) will take.

      The source's permissions are where it starts, narrowed by anything that has since narrowed them. A desktop modifier is the usual one: a source offering a copy and a move while the user holds the key for a move is offering a move now, and reporting both would invite a target to accept the copy the user has just said they do not want. That is the question this answers -- what may be accepted -- and it is the same answer on the enter, the over and the drop, so a target reads one thing throughout a drag rather than one thing while hovering and another at the end.

      It is not a way to ask what the source would have permitted in the absence of the user's choice; nothing carries that, and a target that acted on it would be acting against the choice.

    • isLocal

      public boolean isLocal()
      Returns true when the drag started inside this application rather than in another application or on the desktop. A target that reorders its own items usually only wants to handle local drags, and a target that imports foreign data usually only wants the rest.

    • getFiles

      public String[] getFiles()
      Returns the file paths carried by the drag, or null when it carries none. This is the representation a drag out of a file manager or off the desktop arrives with.

    • getText

      public String getText()
      Returns the plain text carried by the drag, or null when it carries none.

    • getAcceptedAction

      public int getAcceptedAction()
      Returns the action this target has accepted, or NativeDragOperation#ACTION_NONE when it has refused the drop.

    • accept

      public void accept(int action)

      Accepts the drag, telling the operating system what dropping here would do. An action the source does not allow is refused rather than silently substituted, because showing the user a move cursor for a drag that can only copy is worse than showing no cursor.

      Parameters
      • action: one of NativeDragOperation#ACTION_COPY, NativeDragOperation#ACTION_MOVE or NativeDragOperation#ACTION_LINK

    • reject

      public void reject()
      Refuses the drag, so the user sees a "no drop" cursor over this component and no drop event is delivered.