Enables drag-and-drop behaviour for a component and all its sub-components. More...

#include "juce_DragAndDropContainer.h"

Inheritance diagram for juce::DragAndDropContainer:

Classes
class	DragImageComponent

Public Member Functions
	DragAndDropContainer ()
	Creates a DragAndDropContainer.

virtual	~DragAndDropContainer ()
	Destructor.

void	startDragging (const var &sourceDescription, Component sourceComponent, const ScaledImage &dragImage=ScaledImage(), bool allowDraggingToOtherJuceWindows=false, const Point< int > imageOffsetFromMouse=nullptr, const MouseInputSource *inputSourceCausingDrag=nullptr)
	Begins a drag-and-drop operation.

void	startDragging (const var &sourceDescription, Component sourceComponent, Image dragImage, bool allowDraggingToOtherJuceWindows=false, const Point< int > imageOffsetFromMouse=nullptr, const MouseInputSource *inputSourceCausingDrag=nullptr)

bool	isDragAndDropActive () const
	Returns true if something is currently being dragged.

int	getNumCurrentDrags () const
	Returns the number of things currently being dragged.

var	getCurrentDragDescription () const
	Returns the description of the thing that's currently being dragged.

var	getDragDescriptionForIndex (int index) const
	Same as the getCurrentDragDescription() method but takes a touch index parameter.

void	setCurrentDragImage (const ScaledImage &newImage)
	If a drag is in progress, this allows the image being shown to be dynamically updated.

void	setCurrentDragImage (const Image &newImage)

void	setDragImageForIndex (int index, const ScaledImage &newImage)
	Same as the setCurrentDragImage() method but takes a touch index parameter.

void	setDragImageForIndex (int index, const Image &newImage)

Static Public Member Functions
static DragAndDropContainer *	findParentDragContainerFor (Component *childComponent)
	Utility to find the DragAndDropContainer for a given Component.

static bool	performExternalDragDropOfFiles (const StringArray &files, bool canMoveFiles, Component *sourceComponent=nullptr, std::function< void()> callback=nullptr)
	This performs an asynchronous drag-and-drop of a set of files to some external application.

static bool	performExternalDragDropOfText (const String &text, Component *sourceComponent=nullptr, std::function< void()> callback=nullptr)
	This performs an asynchronous drag-and-drop of a block of text to some external application.

Protected Member Functions
virtual bool	shouldDropFilesWhenDraggedExternally (const DragAndDropTarget::SourceDetails &sourceDetails, StringArray &files, bool &canMoveFiles)
	Override this if you want to be able to perform an external drag of a set of files when the user drags outside of this container component.

virtual bool	shouldDropTextWhenDraggedExternally (const DragAndDropTarget::SourceDetails &sourceDetails, String &text)
	Override this if you want to be able to perform an external drag of text when the user drags outside of this container component.

virtual void	dragOperationStarted (const DragAndDropTarget::SourceDetails &)
	Subclasses can override this to be told when a drag starts.

virtual void	dragOperationEnded (const DragAndDropTarget::SourceDetails &)
	Subclasses can override this to be told when a drag finishes.

Detailed Description

Enables drag-and-drop behaviour for a component and all its sub-components.

For a component to be able to make or receive drag-and-drop events, one of its parent components must derive from this class. It's probably best for the top-level component to implement it.

Then to start a drag operation, any sub-component can just call the startDragging() method, and this object will take over, tracking the mouse and sending appropriate callbacks to any child components derived from DragAndDropTarget which the mouse moves over.

Note: If all that you need to do is to respond to files being drag-and-dropped from the operating system onto your component, you don't need any of these classes: you can do this simply by overriding FileDragAndDropTarget::filesDropped().

See also: DragAndDropTarget

@tags{GUI}

Definition at line 50 of file juce_DragAndDropContainer.h.

Constructor & Destructor Documentation

◆ DragAndDropContainer()

juce::DragAndDropContainer::DragAndDropContainer ( )

default

Creates a DragAndDropContainer.

The object that derives from this class must also be a Component.

Member Function Documentation

◆ dragOperationEnded()

void juce::DragAndDropContainer::dragOperationEnded ( const DragAndDropTarget::SourceDetails & )

protectedvirtual

Subclasses can override this to be told when a drag finishes.

Definition at line 566 of file juce_DragAndDropContainer.cpp.

◆ dragOperationStarted()

void juce::DragAndDropContainer::dragOperationStarted ( const DragAndDropTarget::SourceDetails & )

protectedvirtual

Subclasses can override this to be told when a drag starts.

Definition at line 565 of file juce_DragAndDropContainer.cpp.

◆ findParentDragContainerFor()

DragAndDropContainer * juce::DragAndDropContainer::findParentDragContainerFor ( Component * childComponent )

static

Utility to find the DragAndDropContainer for a given Component.

This will search up this component's parent hierarchy looking for the first parent component which is a DragAndDropContainer.

It's useful when a component wants to call startDragging but doesn't know the DragAndDropContainer it should to use.

Obviously this may return nullptr if it doesn't find a suitable component.

Definition at line 550 of file juce_DragAndDropContainer.cpp.

◆ getCurrentDragDescription()

var juce::DragAndDropContainer::getCurrentDragDescription ( ) const

Returns the description of the thing that's currently being dragged.

If nothing's being dragged, this will return a null var, otherwise it'll return the var that was passed into startDragging().

If you are using drag and drop in a multi-touch environment then you should use the getDragDescriptionForIndex() method instead which takes a touch index parameter.

See also: startDragging, getDragDescriptionForIndex

Definition at line 517 of file juce_DragAndDropContainer.cpp.

◆ getDragDescriptionForIndex()

var juce::DragAndDropContainer::getDragDescriptionForIndex ( int index ) const

Same as the getCurrentDragDescription() method but takes a touch index parameter.

See also: getCurrentDragDescription

Definition at line 527 of file juce_DragAndDropContainer.cpp.

◆ getNumCurrentDrags()

int juce::DragAndDropContainer::getNumCurrentDrags ( ) const

Returns the number of things currently being dragged.

Definition at line 512 of file juce_DragAndDropContainer.cpp.

◆ isDragAndDropActive()

bool juce::DragAndDropContainer::isDragAndDropActive ( ) const

Returns true if something is currently being dragged.

Definition at line 507 of file juce_DragAndDropContainer.cpp.

◆ performExternalDragDropOfFiles()

bool juce::DragAndDropContainer::performExternalDragDropOfFiles	(	const StringArray &	files,
		bool	canMoveFiles,
		Component *	sourceComponent = `nullptr`,
		std::function< void()>	callback = `nullptr`
	)

static

This performs an asynchronous drag-and-drop of a set of files to some external application.

You can call this function in response to a mouseDrag callback, and it will use a native operating system drag-and-drop operation to move or copy some files to another application.

Parameters

files	a list of filenames to drag
canMoveFiles	if true, the app that receives the files is allowed to move the files to a new location (if this is appropriate). If false, the receiver is expected to make a copy of them.
sourceComponent	normally, JUCE will assume that the component under the mouse is the source component of the drag, but you can use this parameter to override this.
callback	an optional completion callback that will be called when the operation has ended.

Returns: true if the drag operation was successfully started, or false if it failed for some reason

See also: performExternalDragDropOfText

Definition at line 784 of file juce_Windowing_linux.cpp.

◆ performExternalDragDropOfText()

bool juce::DragAndDropContainer::performExternalDragDropOfText	(	const String &	text,
		Component *	sourceComponent = `nullptr`,
		std::function< void()>	callback = `nullptr`
	)

static

This performs an asynchronous drag-and-drop of a block of text to some external application.

You can call this function in response to a mouseDrag callback, and it will use a native operating system drag-and-drop operation to move or copy some text to another application.

Parameters

text	the text to copy
sourceComponent	Normally, JUCE will assume that the component under the mouse is the source component of the drag, but you can use this parameter to override this.
callback	an optional completion callback that will be called when the operation has ended.

Returns: true if the drag operation was successfully started, or false if it failed for some reason

See also: performExternalDragDropOfFiles

Definition at line 798 of file juce_Windowing_linux.cpp.

◆ setCurrentDragImage() [1/2]

void juce::DragAndDropContainer::setCurrentDragImage ( const Image & newImage )

Definition at line 152 of file juce_DragAndDropContainer.h.

◆ setCurrentDragImage() [2/2]

void juce::DragAndDropContainer::setCurrentDragImage ( const ScaledImage & newImage )

If a drag is in progress, this allows the image being shown to be dynamically updated.

If you are using drag and drop in a multi-touch environment then you should use the setDragImageForIndex() method instead which takes a touch index parameter.

See also: setDragImageForIndex

Definition at line 535 of file juce_DragAndDropContainer.cpp.

◆ setDragImageForIndex() [1/2]

void juce::DragAndDropContainer::setDragImageForIndex	(	int	index,
		const Image &	newImage
	)

Definition at line 161 of file juce_DragAndDropContainer.h.

◆ setDragImageForIndex() [2/2]

void juce::DragAndDropContainer::setDragImageForIndex	(	int	index,
		const ScaledImage &	newImage
	)

Same as the setCurrentDragImage() method but takes a touch index parameter.

See also: setCurrentDragImage

Definition at line 544 of file juce_DragAndDropContainer.cpp.

◆ shouldDropFilesWhenDraggedExternally()

bool juce::DragAndDropContainer::shouldDropFilesWhenDraggedExternally	(	const DragAndDropTarget::SourceDetails &	sourceDetails,
		StringArray &	files,
		bool &	canMoveFiles
	)

protectedvirtual

Override this if you want to be able to perform an external drag of a set of files when the user drags outside of this container component.

This method will be called when a drag operation moves outside the JUCE window, and if you want it to then perform a file drag-and-drop, add the filenames you want to the array passed in, and return true.

Parameters

sourceDetails	information about the source of the drag operation
files	on return, the filenames you want to drag
canMoveFiles	on return, true if it's ok for the receiver to move the files; false if it must make a copy of them (see the performExternalDragDropOfFiles() method)

See also: performExternalDragDropOfFiles, shouldDropTextWhenDraggedExternally

Definition at line 555 of file juce_DragAndDropContainer.cpp.

◆ shouldDropTextWhenDraggedExternally()

bool juce::DragAndDropContainer::shouldDropTextWhenDraggedExternally	(	const DragAndDropTarget::SourceDetails &	sourceDetails,
		String &	text
	)

protectedvirtual

Override this if you want to be able to perform an external drag of text when the user drags outside of this container component.

This method will be called when a drag operation moves outside the JUCE window, and if you want it to then perform a text drag-and-drop, copy the text you want to be dragged into the argument provided and return true.

Parameters

sourceDetails	information about the source of the drag operation
text	on return, the text you want to drag

See also: shouldDropFilesWhenDraggedExternally

Definition at line 560 of file juce_DragAndDropContainer.cpp.

◆ startDragging() [1/2]

void juce::DragAndDropContainer::startDragging	(	const var &	sourceDescription,
		Component *	sourceComponent,
		const ScaledImage &	dragImage = `ScaledImage()`,
		bool	allowDraggingToOtherJuceWindows = `false`,
		const Point< int > *	imageOffsetFromMouse = `nullptr`,
		const MouseInputSource *	inputSourceCausingDrag = `nullptr`
	)

Begins a drag-and-drop operation.

This starts a drag-and-drop operation - call it when the user drags the mouse in your drag-source component, and this object will track mouse movements until the user lets go of the mouse button, and will send appropriate messages to DragAndDropTarget objects that the mouse moves over.

findParentDragContainerFor() is a handy method to call to find the drag container to use for a component.

Parameters

sourceDescription	a string or value to use as the description of the thing being dragged - this will be passed to the objects that might be dropped-onto so they can decide whether they want to handle it
sourceComponent	the component that is being dragged
dragImage	the image to drag around underneath the mouse. If this is a null image, a snapshot of the sourceComponent will be used instead.
allowDraggingToOtherJuceWindows	if true, the dragged component will appear as a desktop window, and can be dragged to DragAndDropTargets that are the children of components other than this one.
imageOffsetFromMouse	if an image has been passed-in, this specifies the offset at which the image should be drawn from the mouse. If it isn't specified, then the image will be centred around the mouse. If an image hasn't been passed-in, this will be ignored.
inputSourceCausingDrag	the mouse input source which started the drag. When calling from within a mouseDown or mouseDrag event, you can pass MouseEvent::source to this method. If this param is nullptr then JUCE will use the mouse input source which is currently dragging. If there are several dragging mouse input sources (which can often occur on mobile) then JUCE will use the mouseInputSource which is closest to the sourceComponent.

Definition at line 407 of file juce_DragAndDropContainer.cpp.

◆ startDragging() [2/2]

void juce::DragAndDropContainer::startDragging	(	const var &	sourceDescription,
		Component *	sourceComponent,
		Image	dragImage,
		bool	allowDraggingToOtherJuceWindows = `false`,
		const Point< int > *	imageOffsetFromMouse = `nullptr`,
		const MouseInputSource *	inputSourceCausingDrag = `nullptr`
	)

Definition at line 103 of file juce_DragAndDropContainer.h.

The documentation for this class was generated from the following files:

juce_gui_basics/mouse/juce_DragAndDropContainer.h
juce_gui_basics/mouse/juce_DragAndDropContainer.cpp
juce_gui_basics/native/juce_Windowing_linux.cpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ DragAndDropContainer()

Member Function Documentation

◆ dragOperationEnded()

◆ dragOperationStarted()

◆ findParentDragContainerFor()

◆ getCurrentDragDescription()

◆ getDragDescriptionForIndex()

◆ getNumCurrentDrags()

◆ isDragAndDropActive()

◆ performExternalDragDropOfFiles()

◆ performExternalDragDropOfText()

◆ setCurrentDragImage() [1/2]

◆ setCurrentDragImage() [2/2]

◆ setDragImageForIndex() [1/2]

◆ setDragImageForIndex() [2/2]

◆ shouldDropFilesWhenDraggedExternally()

◆ shouldDropTextWhenDraggedExternally()

◆ startDragging() [1/2]

◆ startDragging() [2/2]