DropTargetProtocol
public protocol DropTargetProtocol : EventControllerProtocol
GtkDropTarget is an event controller to receive Drag-and-Drop operations.
The most basic way to use a GtkDropTarget to receive drops on a
widget is to create it via [ctorGtk.DropTarget.new], passing in the
GType of the data you want to receive and connect to the
[signalGtk.DropTarget::drop] signal to receive the data:
static gboolean
on_drop (GtkDropTarget *target,
const GValue *value,
double x,
double y,
gpointer data)
{
MyWidget *self = data;
// Call the appropriate setter depending on the type of data
// that we received
if (G_VALUE_HOLDS (value, G_TYPE_FILE))
my_widget_set_file (self, g_value_get_object (value));
else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
my_widget_set_pixbuf (self, g_value_get_object (value));
else
return FALSE;
return TRUE;
}
static void
my_widget_init (MyWidget *self)
{
GtkDropTarget *target =
gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);
// This widget accepts two types of drop types: GFile objects
// and GdkPixbuf objects
gtk_drop_target_set_gtypes (target, (GTypes [2]) {
G_TYPE_FILE,
GDK_TYPE_PIXBUF,
}, 2);
gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
}
GtkDropTarget supports more options, such as:
- rejecting potential drops via the [signal
Gtk.DropTarget::accept] signal and the [methodGtk.DropTarget.reject] function to let other drop targets handle the drop - tracking an ongoing drag operation before the drop via the
[signal
Gtk.DropTarget::enter], [signalGtk.DropTarget::motion] and [signalGtk.DropTarget::leave] signals - configuring how to receive data by setting the
[property
Gtk.DropTarget:preload] property and listening for its availability via the [propertyGtk.DropTarget:value] property
However, GtkDropTarget is ultimately modeled in a synchronous way
and only supports data transferred via GType. If you want full control
over an ongoing drop, the [classGtk.DropTargetAsync] object gives you
this ability.
While a pointer is dragged over the drop target’s widget and the drop
has not been rejected, that widget will receive the
GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget.
If you are not interested in receiving the drop, but just want to update
UI state during a Drag-and-Drop operation (e.g. switching tabs), you can
use [classGtk.DropControllerMotion].
The DropTargetProtocol protocol exposes the methods and properties of an underlying GtkDropTarget instance.
The default implementation of these can be found in the protocol extension below.
For a concrete class that implements these methods and properties, see DropTarget.
Alternatively, use DropTargetRef as a lighweight, unowned reference if you already have an instance you just want to use.
-
Untyped pointer to the underlying
GtkDropTargetinstance.Declaration
Swift
var ptr: UnsafeMutableRawPointer! { get } -
drop_target_ptrDefault implementationTyped pointer to the underlying
GtkDropTargetinstance.Default Implementation
Return the stored, untyped pointer as a typed pointer to the
GtkDropTargetinstance.Declaration
Swift
var drop_target_ptr: UnsafeMutablePointer<GtkDropTarget>! { get } -
Required Initialiser for types conforming to
DropTargetProtocolDeclaration
Swift
init(raw: UnsafeMutableRawPointer)
-
bind(property:Extension methodto: _: flags: transformFrom: transformTo: ) Bind a
DropTargetPropertyNamesource property to a given target object.Declaration
Swift
@discardableResult @inlinable func bind<Q, T>(property source_property: DropTargetPropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocolParameters
source_propertythe source property to bind
targetthe target object to bind to
target_propertythe target property to bind to
flagsthe flags to pass to the
Bindingtransform_fromValueTransformerto use for forward transformationtransform_toValueTransformerto use for backwards transformationReturn Value
binding reference or
nilin case of an error -
get(property:Extension method) Get the value of a DropTarget property
Declaration
Swift
@inlinable func get(property: DropTargetPropertyName) -> GLibObject.ValueParameters
propertythe property to get the value for
Return Value
the value of the named property
-
set(property:Extension methodvalue: ) Set the value of a DropTarget property. Note that this will only have an effect on properties that are writable and not construct-only!
Declaration
Swift
@inlinable func set(property: DropTargetPropertyName, value v: GLibObject.Value)Parameters
propertythe property to get the value for
Return Value
the value of the named property
-
connect(signal:Extension methodflags: handler: ) Connect a Swift signal handler to the given, typed
DropTargetSignalNamesignalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: DropTargetSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> IntParameters
signalThe signal to connect
flagsThe connection flags to use
dataA pointer to user data to provide to the callback
destroyDataA
GClosureNotifyC function to destroy the data pointed to byuserDatahandlerThe Swift signal handler (function or callback) to invoke on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
connect(signal:Extension methodflags: data: destroyData: signalHandler: ) Connect a C signal handler to the given, typed
DropTargetSignalNamesignalDeclaration
Swift
@discardableResult @inlinable func connect(signal s: DropTargetSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> IntParameters
signalThe signal to connect
flagsThe connection flags to use
dataA pointer to user data to provide to the callback
destroyDataA
GClosureNotifyC function to destroy the data pointed to byuserDatasignalHandlerThe C function to be called on the given signal
Return Value
The signal handler ID (always greater than 0 for successful connections)
-
onAccept(flags:Extension methodhandler: ) Emitted on the drop site when a drop operation is about to begin.
If the drop is not accepted,
falsewill be returned and the drop target will ignore the drop. Iftrueis returned, the drop is accepted for now but may be rejected later via a call to [methodGtk.DropTarget.reject] or ultimately by returningfalsefrom a [signalGtk.DropTarget::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 depends on the data, this function should return
true, the [propertyGtk.DropTarget:preload] property should be set and the value should be inspected via thenotify:valuesignal, calling [methodGtk.DropTarget.reject] if required.Note
This represents the underlyingacceptsignalDeclaration
Swift
@discardableResult @inlinable func onAccept(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ drop: Gdk.DropRef) -> Bool) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
dropthe
GdkDrophandlertrueifdropis accepted Run the given callback whenever theacceptsignal is emitted -
acceptSignalExtension methodTyped
acceptsignal for using theconnect(signal:)methodsDeclaration
Swift
static var acceptSignal: DropTargetSignalName { get } -
onDrop(flags:Extension methodhandler: ) 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
falseand no further processing is necessary.Otherwise, the handler returns
true. In this case, this handler will accept the drop. The handler is responsible for using the givenvalueand performing the drop operation.Note
This represents the underlyingdropsignalDeclaration
Swift
@discardableResult @inlinable func onDrop(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ value: GLibObject.ValueRef, _ x: Double, _ y: Double) -> Bool) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
valuethe
GValuebeing droppedxthe x coordinate of the current pointer position
ythe y coordinate of the current pointer position
handlerwhether the drop was accepted at the given pointer position Run the given callback whenever the
dropsignal is emitted -
dropSignalExtension methodTyped
dropsignal for using theconnect(signal:)methodsDeclaration
Swift
static var dropSignal: DropTargetSignalName { get } -
onEnter(flags:Extension methodhandler: ) Emitted on the drop site when the pointer enters the widget.
It can be used to set up custom highlighting.
Note
This represents the underlyingentersignalDeclaration
Swift
@discardableResult @inlinable func onEnter(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ x: Double, _ y: Double) -> Gdk.DragAction) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
xthe x coordinate of the current pointer position
ythe y coordinate of the current pointer position
handlerPreferred action for this drag operation or 0 if dropping is not supported at the current
x,ylocation. Run the given callback whenever theentersignal is emitted -
enterSignalExtension methodTyped
entersignal for using theconnect(signal:)methodsDeclaration
Swift
static var enterSignal: DropTargetSignalName { get } -
onLeave(flags:Extension methodhandler: ) Emitted on the drop site when the pointer leaves the widget.
Its main purpose it to undo things done in [signal
Gtk.DropTarget::enter].Note
This represents the underlyingleavesignalDeclaration
Swift
@discardableResult @inlinable func onLeave(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
handlerThe signal handler to call Run the given callback whenever the
leavesignal is emitted -
leaveSignalExtension methodTyped
leavesignal for using theconnect(signal:)methodsDeclaration
Swift
static var leaveSignal: DropTargetSignalName { get } -
onMotion(flags:Extension methodhandler: ) Emitted while the pointer is moving over the drop target.
Note
This represents the underlyingmotionsignalDeclaration
Swift
@discardableResult @inlinable func onMotion(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ x: Double, _ y: Double) -> Gdk.DragAction) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
xthe x coordinate of the current pointer position
ythe y coordinate of the current pointer position
handlerPreferred action for this drag operation or 0 if dropping is not supported at the current
x,ylocation. Run the given callback whenever themotionsignal is emitted -
motionSignalExtension methodTyped
motionsignal for using theconnect(signal:)methodsDeclaration
Swift
static var motionSignal: DropTargetSignalName { get } -
onNotifyActions(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::actionssignalDeclaration
Swift
@discardableResult @inlinable func onNotifyActions(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyActionssignal is emitted -
notifyActionsSignalExtension methodTyped
notify::actionssignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyActionsSignal: DropTargetSignalName { get } -
onNotifyCurrentDrop(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::current-dropsignalDeclaration
Swift
@discardableResult @inlinable func onNotifyCurrentDrop(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyCurrentDropsignal is emitted -
notifyCurrentDropSignalExtension methodTyped
notify::current-dropsignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyCurrentDropSignal: DropTargetSignalName { get } -
onNotifyDrop(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::dropsignalDeclaration
Swift
@discardableResult @inlinable func onNotifyDrop(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyDropsignal is emitted -
notifyDropSignalExtension methodTyped
notify::dropsignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyDropSignal: DropTargetSignalName { get } -
onNotifyFormats(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::formatssignalDeclaration
Swift
@discardableResult @inlinable func onNotifyFormats(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyFormatssignal is emitted -
notifyFormatsSignalExtension methodTyped
notify::formatssignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyFormatsSignal: DropTargetSignalName { get } -
onNotifyPreload(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::preloadsignalDeclaration
Swift
@discardableResult @inlinable func onNotifyPreload(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyPreloadsignal is emitted -
notifyPreloadSignalExtension methodTyped
notify::preloadsignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyPreloadSignal: DropTargetSignalName { get } -
onNotifyValue(flags:Extension methodhandler: ) The notify signal is emitted on an object when one of its properties has its value set through
g_object_set_property(),g_object_set(), et al.Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with
G_PARAM_EXPLICIT_NOTIFY, then any call tog_object_set_property()results innotifybeing emitted, even if the new value is the same as the old. If they did passG_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly callg_object_notify()org_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the
g_signal_connect()call, like this:(C Language Example):
g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view)It is important to note that you must use canonical parameter names as detail strings for the notify signal.
Note
This represents the underlyingnotify::valuesignalDeclaration
Swift
@discardableResult @inlinable func onNotifyValue(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DropTargetRef, _ pspec: ParamSpecRef) -> Void) -> IntParameters
flagsFlags
unownedSelfReference to instance of self
pspecthe
GParamSpecof the property which changed.handlerThe signal handler to call Run the given callback whenever the
notifyValuesignal is emitted -
notifyValueSignalExtension methodTyped
notify::valuesignal for using theconnect(signal:)methodsDeclaration
Swift
static var notifyValueSignal: DropTargetSignalName { get }
-
getActions()Extension methodGets the actions that this drop target supports.
Declaration
Swift
@inlinable func getActions() -> Gdk.DragAction -
getCurrentDrop()Extension methodGets the currently handled drop operation.
If no drop operation is going on,
nilis returned.Declaration
Swift
@inlinable func getCurrentDrop() -> Gdk.DropRef! -
getDrop()Extension methodGets the currently handled drop operation.
If no drop operation is going on,
nilis returned.get_drop is deprecated: Use [method@Gtk.DropTarget.get_current_drop] instead
Declaration
Swift
@available(*, deprecated) @inlinable func getDrop() -> Gdk.DropRef! -
getFormats()Extension methodGets the data formats that this drop target accepts.
If the result is
nil, all formats are expected to be supported.Declaration
Swift
@inlinable func getFormats() -> Gdk.ContentFormatsRef! -
getGtypes(nTypes:Extension method) Gets the list of supported
GTypes that can be dropped on the target.If no types have been set,
NULLwill be returned.Declaration
Swift
@inlinable func getGtypes(nTypes: UnsafeMutablePointer<gsize>! = nil) -> UnsafePointer<GType>! -
getPreload()Extension methodGets whether data should be preloaded on hover.
Declaration
Swift
@inlinable func getPreload() -> Bool -
getValue()Extension methodGets the current drop data, as a
GValue.Declaration
Swift
@inlinable func getValue() -> GLibObject.ValueRef! -
reject()Extension methodRejects the ongoing drop operation.
If no drop operation is ongoing, i.e when [property
Gtk.DropTarget:current-drop] isnil, this function does nothing.This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.
Declaration
Swift
@inlinable func reject() -
set(actions:Extension method) Sets the actions that this drop target supports.
Declaration
Swift
@inlinable func set(actions: Gdk.DragAction) -
setGtypes(types:Extension methodnTypes: ) Sets the supported
GTypesfor this drop target.Declaration
Swift
@inlinable func setGtypes(types: UnsafeMutablePointer<GType>! = nil, nTypes: Int) -
set(preload:Extension method) Sets whether data should be preloaded on hover.
Declaration
Swift
@inlinable func set(preload: Bool) -
actionsExtension methodThe
GdkDragActionsthat this drop target supports.Declaration
Swift
@inlinable var actions: Gdk.DragAction { get nonmutating set } -
currentDropExtension methodGets the currently handled drop operation.
If no drop operation is going on,
nilis returned.Declaration
Swift
@inlinable var currentDrop: Gdk.DropRef! { get } -
dropExtension methodThe
GdkDropthat is currently being performed.drop is deprecated: Use [property@Gtk.DropTarget:current-drop] instead
Declaration
Swift
@inlinable var drop: Gdk.DropRef! { get } -
formatsExtension methodThe
GdkContentFormatsthat determine the supported data formats.Declaration
Swift
@inlinable var formats: Gdk.ContentFormatsRef! { get } -
preloadExtension methodWhether the drop data should be preloaded when the pointer is only hovering over the widget but has not been released.
Setting this property allows finer grained reaction to an ongoing drop at the cost of loading more data.
The default value for this property is
falseto avoid downloading huge amounts of data by accident.For example, if somebody drags a full document of gigabytes of text from a text editor across a widget with a preloading drop target, this data will be downloaded, even if the data is ultimately dropped elsewhere.
For a lot of data formats, the amount of data is very small (like
GDK_TYPE_RGBA), so enabling this property does not hurt at all. And for local-only Drag-and-Drop operations, no data transfer is done, so enabling it there is free.Declaration
Swift
@inlinable var preload: Bool { get nonmutating set } -
valueExtension methodThe value for this drop operation.
This is
nilif the data has not been loaded yet or no drop operation is going on.Data may be available before the [signal
Gtk.DropTarget::drop] signal gets emitted - for example when the [propertyGtk.DropTarget:preload] property is set. You can use thenotifysignal to be notified of available data.Declaration
Swift
@inlinable var value: GLibObject.ValueRef! { get }
View on GitHub
Install in Dash
DropTargetProtocol Protocol Reference