Package org.gnome.gtk

Class DropTargetAsync

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gtk.EventController

org.gnome.gtk.DropTargetAsync

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class DropTargetAsync
extends EventController

An event controller to receive Drag-and-Drop operations, asynchronously.

It is the more complete but also more complex method of handling drop operations compared to DropTarget, and you should only use it if GtkDropTarget doesn't provide all the features you need.

To use a GtkDropTargetAsync to receive drops on a widget, you create a GtkDropTargetAsync object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with Widget.addController(org.gnome.gtk.EventController).

During a drag operation, the first signal that a GtkDropTargetAsync emits is Gtk.DropTargetAsync::accept, which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the ::accept signal accepts the drop if it finds a compatible data format and an action that is supported on both sides.

If it is, and the widget becomes a target, you will receive a Gtk.DropTargetAsync::drag-enter signal, followed by Gtk.DropTargetAsync::drag-motion signals as the pointer moves, optionally a Gtk.DropTargetAsync::drop signal when a drop happens, and finally a Gtk.DropTargetAsync::drag-leave signal when the pointer moves off the widget.

The ::drag-enter and ::drag-motion handler return a GdkDragAction to update the status of the ongoing operation. The ::drop handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling Drop.finish(java.util.Set<org.gnome.gdk.DragAction>).

Between the ::drag-enter and ::drag-leave signals the widget is a current drop target, and will receive the StateFlags.DROP_ACTIVE state, which can be used by themes to style the widget as a drop target.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	DropTargetAsync.AcceptCallback	Functional interface declaration of the AcceptCallback callback.
static class	DropTargetAsync.Builder<B extends DropTargetAsync.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	DropTargetAsync.DragEnterCallback	Functional interface declaration of the DragEnterCallback callback.
static interface	DropTargetAsync.DragLeaveCallback	Functional interface declaration of the DragLeaveCallback callback.
static interface	DropTargetAsync.DragMotionCallback	Functional interface declaration of the DragMotionCallback callback.
static interface	DropTargetAsync.DropCallback	Functional interface declaration of the DropCallback callback.
static class	DropTargetAsync.DropTargetAsyncClass

Nested classes/interfaces inherited from class org.gnome.gtk.EventController

EventController.EventController$Impl, EventController.EventControllerClass

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
DropTargetAsync()	Creates a new DropTargetAsync.
DropTargetAsync(MemorySegment address)	Create a DropTargetAsync proxy instance for the provided memory address.
DropTargetAsync(@Nullable ContentFormats formats, Set<DragAction> actions)	Creates a new GtkDropTargetAsync object.
DropTargetAsync(@Nullable ContentFormats formats, DragAction... actions)	Creates a new GtkDropTargetAsync object.

Method Summary

Modifier and Type	Method	Description
protected DropTargetAsync	asParent()	Returns this instance as if it were its parent type.
static DropTargetAsync.Builder<? extends DropTargetAsync.Builder>	builder()	A DropTargetAsync.Builder object constructs a DropTargetAsync with the specified properties.
boolean	emitAccept(@Nullable Drop drop)	Emits the "accept" signal.
Set<DragAction>	emitDragEnter(@Nullable Drop drop, double x, double y)	Emits the "drag-enter" signal.
void	emitDragLeave(@Nullable Drop drop)	Emits the "drag-leave" signal.
Set<DragAction>	emitDragMotion(@Nullable Drop drop, double x, double y)	Emits the "drag-motion" signal.
boolean	emitDrop(@Nullable Drop drop, double x, double y)	Emits the "drop" signal.
Set<DragAction>	getActions()	Gets the actions that this drop target supports.
@Nullable ContentFormats	getFormats()	Gets the data formats that this drop target accepts.
static @Nullable Type	getType()	Get the GType of the DropTargetAsync class
SignalConnection<DropTargetAsync.AcceptCallback>	onAccept(DropTargetAsync.AcceptCallback handler)	Emitted on the drop site when a drop operation is about to begin.
SignalConnection<DropTargetAsync.DragEnterCallback>	onDragEnter(DropTargetAsync.DragEnterCallback handler)	Emitted on the drop site when the pointer enters the widget.
SignalConnection<DropTargetAsync.DragLeaveCallback>	onDragLeave(DropTargetAsync.DragLeaveCallback handler)	Emitted on the drop site when the pointer leaves the widget.
SignalConnection<DropTargetAsync.DragMotionCallback>	onDragMotion(DropTargetAsync.DragMotionCallback handler)	Emitted while the pointer is moving over the drop target.
SignalConnection<DropTargetAsync.DropCallback>	onDrop(DropTargetAsync.DropCallback handler)	Emitted on the drop site when the user drops the data onto the widget.
void	rejectDrop(Drop drop)	Sets the drop as not accepted on this drag site.
void	setActions(Set<DragAction> actions)	Sets the actions that this drop target supports.
void	setActions(DragAction... actions)	Sets the actions that this drop target supports.
void	setFormats(@Nullable ContentFormats formats)	Sets the data formats that this drop target will accept.

Methods inherited from class org.gnome.gtk.EventController

getCurrentEvent, getCurrentEventDevice, getCurrentEventState, getCurrentEventTime, getName, getPropagationLimit, getPropagationPhase, getWidget, reset, setName, setPropagationLimit, setPropagationPhase, setStaticName

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class org.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

DropTargetAsync

public DropTargetAsync(MemorySegment address)

Create a DropTargetAsync proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

DropTargetAsync

public DropTargetAsync(@Nullable ContentFormats formats,
 Set<DragAction> actions)

Creates a new GtkDropTargetAsync object.

Parameters:

formats - the supported data formats

actions - the supported actions

DropTargetAsync

public DropTargetAsync(@Nullable ContentFormats formats,
 DragAction... actions)

Creates a new GtkDropTargetAsync object.

Parameters:

formats - the supported data formats

actions - the supported actions

DropTargetAsync

public DropTargetAsync()

Creates a new DropTargetAsync.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the DropTargetAsync class

Returns:

the GType

asParent

protected DropTargetAsync asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class EventController

getActions

public Set<DragAction> getActions()

Gets the actions that this drop target supports.

Returns:

the actions that this drop target supports

getFormats

public @Nullable ContentFormats getFormats()

Gets the data formats that this drop target accepts.

If the result is null, all formats are expected to be supported.

Returns:

the supported data formats

rejectDrop

public void rejectDrop(Drop drop)

Sets the drop as not accepted on this drag site.

This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.

Parameters:

drop - the GdkDrop of an ongoing drag operation

setActions

public void setActions(Set<DragAction> actions)

Sets the actions that this drop target supports.

Parameters:

actions - the supported actions

setActions

public void setActions(DragAction... actions)

Sets the actions that this drop target supports.

Parameters:

actions - the supported actions

setFormats

public void setFormats(@Nullable ContentFormats formats)

Sets the data formats that this drop target will accept.

Parameters:

formats - the supported data formats or null for any format

onAccept

public SignalConnection<DropTargetAsync.AcceptCallback> onAccept(DropTargetAsync.AcceptCallback handler)

Emitted on the drop site when a drop operation is about to begin.

If the drop is not accepted, false will be returned and the drop target will ignore the drop. If true is returned, the drop is accepted for now but may be rejected later via a call to rejectDrop(org.gnome.gdk.Drop) or ultimately by returning false from a Gtk.DropTargetAsync::drop handler.

The default handler for this signal decides whether to accept the drop based on the formats provided by the drop.

If the decision whether the drop will be accepted or rejected needs further processing, such as inspecting the data, this function should return true and proceed as is drop was accepted and if it decides to reject the drop later, it should call rejectDrop(org.gnome.gdk.Drop).

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DropTargetAsync.AcceptCallback.run(org.gnome.gdk.Drop)

emitAccept

public boolean emitAccept(@Nullable Drop drop)

Emits the "accept" signal. See onAccept(org.gnome.gtk.DropTargetAsync.AcceptCallback).

onDragEnter

public SignalConnection<DropTargetAsync.DragEnterCallback> onDragEnter(DropTargetAsync.DragEnterCallback handler)

Emitted on the drop site when the pointer enters the widget.

It can be used to set up custom highlighting.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DropTargetAsync.DragEnterCallback.run(org.gnome.gdk.Drop, double, double)

emitDragEnter

public Set<DragAction> emitDragEnter(@Nullable Drop drop,
 double x,
 double y)

Emits the "drag-enter" signal. See onDragEnter(org.gnome.gtk.DropTargetAsync.DragEnterCallback).

onDragLeave

public SignalConnection<DropTargetAsync.DragLeaveCallback> onDragLeave(DropTargetAsync.DragLeaveCallback handler)

Emitted on the drop site when the pointer leaves the widget.

Its main purpose it to undo things done in GtkDropTargetAsync::drag-enter.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DropTargetAsync.DragLeaveCallback.run(org.gnome.gdk.Drop)

emitDragLeave

public void emitDragLeave(@Nullable Drop drop)

Emits the "drag-leave" signal. See onDragLeave(org.gnome.gtk.DropTargetAsync.DragLeaveCallback).

onDragMotion

public SignalConnection<DropTargetAsync.DragMotionCallback> onDragMotion(DropTargetAsync.DragMotionCallback handler)

Emitted while the pointer is moving over the drop target.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DropTargetAsync.DragMotionCallback.run(org.gnome.gdk.Drop, double, double)

emitDragMotion

public Set<DragAction> emitDragMotion(@Nullable Drop drop,
 double x,
 double y)

Emits the "drag-motion" signal. See onDragMotion(org.gnome.gtk.DropTargetAsync.DragMotionCallback).

onDrop

public SignalConnection<DropTargetAsync.DropCallback> onDrop(DropTargetAsync.DropCallback handler)

Emitted on the drop site when the user drops the data onto the widget.

The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary.

Otherwise, the handler returns true. In this case, this handler will accept the drop. The handler must ensure that Drop.finish(java.util.Set<org.gnome.gdk.DragAction>) is called to let the source know that the drop is done. The call to Drop.finish(java.util.Set<org.gnome.gdk.DragAction>) must only be done when all data has been received.

To receive the data, use one of the read functions provided by Drop such as Drop.readAsync(java.lang.String[], int, org.gnome.gio.Cancellable, org.gnome.gio.AsyncReadyCallback) or Drop.readValueAsync(org.gnome.glib.Type, int, org.gnome.gio.Cancellable, org.gnome.gio.AsyncReadyCallback).

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DropTargetAsync.DropCallback.run(org.gnome.gdk.Drop, double, double)

emitDrop

public boolean emitDrop(@Nullable Drop drop,
 double x,
 double y)

Emits the "drop" signal. See onDrop(org.gnome.gtk.DropTargetAsync.DropCallback).

builder

public static DropTargetAsync.Builder<? extends DropTargetAsync.Builder> builder()

A DropTargetAsync.Builder object constructs a DropTargetAsync with the specified properties. Use the various set...() methods to set properties, and finish construction with DropTargetAsync.Builder.build().

Returns:

the builder object