Package limn.transfer

Class Drag

java.lang.Object
limn.transfer.Drag
public final class Drag extends Object
A drag about to begin: what it carries, what may be done with it, and what the source wants to hear when it is over. A widget answers one from onDragStart: 

 protected Drag onDragStart(DragStartEvent event) {
     Order order = orderAt(event.x(), event.y());
     return order == null ? null
             : Drag.of(Transfer.of(ORDER, order).with(DataFormat.TEXT, order.summary()))
                     .allow(DropAction.MOVE, DropAction.COPY)
                     .describedAs("Order " + order.number())
                     .onEnd(action -> { if (action == DropAction.MOVE) remove(order); });
 }

  • Method Details

    • of

      public static Drag of(Transfer content)
      Parameters:
      content - what is dragged
      Returns:
      a drag that allows a copy, until allow(limn.transfer.DropAction, limn.transfer.DropAction...) says otherwise

    • allow

      public Drag allow(DropAction first, DropAction... more)
      Says what a target may do with the content. With no modifier key held, the first is what is proposed.
      Parameters:
      first - the action the source prefers
      more - the others it allows
      Returns:
      this drag

    • image

      public Drag image(Image newImage, float hotSpotX, float hotSpotY)
      Shows a picture under the pointer while the drag lasts, in place of the part of the source widget a preview(float, float, float, float) would show.
      Parameters:
      newImage - the picture
      hotSpotX - where in it the pointer is, from its left edge, in points
      hotSpotY - where in it the pointer is, from its top edge, in points
      Returns:
      this drag

    • preview

      public Drag preview(float x, float y, float width, float height)
      Says which part of the source widget is shown under the pointer while the drag lasts: the row, the card, the picture that is being dragged, as it is painted. Without this, and without an image, a small widget is shown whole and a large one as the part around the point where the drag began.
      Parameters:
      x - the part's left edge, in the source widget's own coordinates
      y - the part's top edge, in the source widget's own coordinates
      width - its width
      height - its height
      Returns:
      this drag

    • preview

      public Drag preview(float width, float height, float holdX, float holdY, Consumer<Canvas> painter)
      Shows under the pointer what the source paints for it: the dragged thing alone, on nothing. The painter is handed a canvas that is transparent, width by height, with its origin at the top left, and draws only the item: a card with its rounded corners, a picture with its own transparency. What it does not paint stays see-through, over this window and over any other program's. It may be called more than once, on the UI thread, while the drag lasts.
      Parameters:
      width - the width of what is painted, in points
      height - its height
      holdX - where in it the pointer holds it, from its left edge
      holdY - where in it the pointer holds it, from its top edge
      painter - paints the dragged thing at the origin
      Returns:
      this drag

    • previewPainter

      public @Nullable Consumer<Canvas> previewPainter()
      Returns:
      what paints the dragged thing alone, or null when the preview is a part of the source widget, or a picture, or nothing

    • noPreview

      public Drag noPreview()
      Shows nothing under the pointer but the pointer itself.
      Returns:
      this drag

    • hasPreviewPart

      public boolean hasPreviewPart()
      Returns:
      whether preview(float, float, float, float) named a part of the source widget

    • isPreviewOff

      public boolean isPreviewOff()
      Returns:
      whether noPreview() was asked for

    • previewX

      public float previewX()
      Returns:
      the left edge of the part to show, in the source widget's coordinates

    • previewY

      public float previewY()
      Returns:
      the top edge of the part to show, in the source widget's coordinates

    • previewWidth

      public float previewWidth()
      Returns:
      the width of the part to show

    • previewHeight

      public float previewHeight()
      Returns:
      the height of the part to show

    • describedAs

      public Drag describedAs(String what)
      Names what is dragged for someone who cannot see it: a keyboard drag announces "Dragging" and this.
      Parameters:
      what - the name, in the user's language
      Returns:
      this drag

    • withinWindow

      public Drag withinWindow()
      Keeps the drag inside the window it began in: it is never handed to the system, and no other program is offered it. What a table's column header is, for one.
      Returns:
      this drag

    • onEnd

      public Drag onEnd(Consumer<@Nullable DropAction> result)
      Hears the end of the drag, once, on the UI thread: the action a target carried out, and no action at all when the drag was cancelled or nothing took it.
      Parameters:
      result - what hears it
      Returns:
      this drag

    • content

      public Transfer content()
      Returns:
      what is dragged

    • actions

      public Set<DropAction> actions()
      Returns:
      what a target may do, the source's preference first

    • image

      public @Nullable Image image()
      Returns:
      the picture shown under the pointer, or null

    • hotSpotX

      public float hotSpotX()
      Returns:
      where in the picture the pointer is, from its left edge

    • hotSpotY

      public float hotSpotY()
      Returns:
      where in the picture the pointer is, from its top edge

    • description

      public String description()
      Returns:
      the name given with describedAs(java.lang.String), or the empty string

    • isWithinWindow

      public boolean isWithinWindow()
      Returns:
      whether the drag stays in its window

    • end

      public void end(@Nullable DropAction action)
      Tells the source the drag is over; for the scene, or a backend, that drove it. The first call tells, the others do nothing.
      Parameters:
      action - what a target carried out, or null