Configuring Dragging Data

TNGDropSource component allows to initiate dragging operation. Dragging data should be configured first using TNGDropSource.Data property. The property provide access to TNGSourceData object, which declares many methods to manipulate dragging data: Add, AddText, AddUnicodeText, AddBitmap, AddDib, Clear, Remove, HasFormat, HasAny, Count and Items.

The most important methods are Add and AddXXX methods, which allows to add some data to drop source. Formally, any data can be added via Add method using required data format class:

NGDropSource1.Data.Add(TNGTextFormat.Data('My dragging text'));

Since built-in formats has shortcuts in the form of CF.XXX, the code can be clarified:

NGDropSource1.Data.Add(CF.TEXT.Data('My dragging text'));

Moreover, special AddXXX methods are provided for some formats to make code even more simpler:

NGDropSource1.Data.AddText('My dragging text');

To provide high level of control, NG Drag&Drop allows to work with data formats formally, independently and explicitly. So, any combination of required data formats can be added to dragging data:

NGDropSource1.Data.Add(CF.URL.Data('http://www.google.com'));

NGDropSource1.Data.AddText('http://www.google.com');

NGDropSource1.Data.AddUnicodeText('http://www.google.com');

NGDropSource1.Data.Add(CF.FILEDESCRIPTOR.Data(...));

NGDropSource1.Data.Add(CF.FILECONTENTS.Data(...));

The above example shows dragging data configuration to allow dragging URL to browser (via CF.URL format), text editors (via CF.TEXT and CF.UNICODETEXT formats) and to Windows file explorer, creating a file link to web page (via CF.FILEDESCRIPTOR and CF.FILECONTENTS) formats. Please look at Data Formats section for more information about data supported formats.

Performing Drag&Drop Operation

After source data has been configured the drag&drop operation can be executed. To begin drag&drop operation Execute method of TNGDropSource component should be called:

NGDropSource1.Execute;

The method acts like modal dialogs executing methods and do not return until the drag&drop operation ends. Typically, drag&drop operation should be started from some control's OnMouseDown event handle, that is, when the mouse button is down. In usual cases its not a good idea to initiate drag&drop operation from OnClick event handler, because at this point mouse button is already up.

procedure TForm1.Panel1MouseDown(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Integer);
begin
  NGDropSource1.Data.AddText('My dragging text');
  NGDropSource1.Execute;
end;

NG Drag&Drop provides automatic detecting of mouse buttons state change; it remembers the state at the beginning of the drag and cancel drag&drop operation, if state is changed. This default algorithm can be customized using OnQueryContinueDrag event.

Also, drag&drop operation is canceled when Escape key is pressed.

Usually, dragging data is configured for each drag&drop operation independently, so, TNGDropSource component provides AutoClear property, which is set to True by default, and forces the component to clear dragging data after each Execute method call.

Execute method allows to specify allowed drop effects, which can include deMove, deCopy or deLink. If the parameter is omitted, all of these effects are allowed. The method returns the actual effect, which has been chosen by the target during drag&drop operation, or - deNone, if the operation has been canceled. To learn more about drop effects please read Drop Effects section.

Fluent Interface

Since drag&drop operation executions are usually tiny and contains only few lines of code, NG Drag&Drop provides special API for executing drag&drop operations even without placing the component on the form. The API is provided by NGDropSource global function, which returns special TNGDropSource.TBuilder object and can be used like this:

NGDropSource.AddText('My dragging text')

.AddUnicodeText('My dragging text')

.Execute;

It contains, actually, the same Add, AddXXX and Execute methods as in previously discussed TNGDropSource component.

Data Dragging as Source

Data Dragging as Source

Configuring Dragging Data

Performing Drag&Drop Operation

Fluent Interface