QDrop |
Using QDrop |
This is a brief tutorial section intended to guide your first steps with QDrop.
QDrop has only a few commands that you will very quickly learn how to use. Incorporating it into an existing database takes minutes and the results are immediately visible and impressive. Drag+drop is intuitive and user-friendly, and it makes a difference that your users will appreciate very much.
In a nutshell, QDrop lets you do the following:
Here are three simple steps for having QDrop up and running in your application:
Open your form in 4D's Design environment Form Editor and draw a QDrop plug-in area where you want the drop area to be. In order to be compatible with the snippets presented in this section, name the area variable xDrop. Obviously you can assign any valid variable name.
In the drag and drop sequence there is a drag phase and a drop phase. During dragging the item is validated against a list of accepted file kinds, in order to conclude whether the dropping should be allowed or not. If dragging is accepted, the drop phase executes and appropriate action is taken by the developer.
In QDrop, dragged items are files or folders, so validation is about the kind of the file being dragged. A list of acceptable file kinds is mandatory.
You will use the command QD_SetDroppableFileExtensions, which works on both platforms and sets up the accepted files filter based on filename extensions.
Prepare an array of the filename extensions that you want the area to accept, then associate the array with the area reference. Note that the filename extensions must not include the leading period character (".").
The simplest cases
Configure QDrop for a few individually declared filename extensions. The example below configures QDrop to accept text (txt) and JPEG (jpg) files:
C_LONGINT($error) ARRAY STRING(15;$extensions;2)
|
These are not real filename extensions. Magic types are handy because they are sort of wildcards: they represent entire categories of files at one shot.
For example, if you wanted to configure QDrop for accepting all image files supported by QuickTime, you should list at least 12 extensions (pct, tif, jpg, gif, etc) and still be unsure because the list of QT-supported image files depends on the specific installation of QT. These hassles can be avoided by using a magic type.
Magic types are:
qd_QTImageMagic
): images supported by QuickTime
qd_QTImageMagic
): movies supported by QuickTime
qd_folderMagic
): folders
qd_anyFileMagic
): all files
Normal types can be mixed with magic types at any time as in this snippet:
C_LONGINT
($error)
ARRAY STRING(15;$fileTypes;3)
$fileTypes{1}:="TEXT"
$fileTypes{2}:=qd_QTImageMagic
$fileTypes{3}:=qd_folderMagic
$error:=QD_SetDroppableFileTypes (xDrop;$fileTypes)
![]() |
QuickTime-related magic types work only if QuickTime is installed on the computer. |
On Mac OS X, besides filename extensions, Uniform Type Identifiers can be used for setting up the accepted files filter. UTIs are the modern replacement for Macintosh file types, the 4-character codes that have been used traditionally for identifying file kinds on Mac OS.
The following example shows how to configure a plug-in area for accepting text files and JPEG images by using Uniform Type Identifiers:
C_LONGINT($error) ARRAY STRING(255;$UTIs;2)
|
Uniform Type Identifiers provide much more flexibility than file type codes and filename extensions: they also define classes of file kinds. The following example shows how to configure a plug-in area for accepting any kind of image or movie (not just those supported by QuickTime):
C_LONGINT($error) ARRAY STRING(255;$UTIs;2)
|
The next important configuration element is the installation of a handler method. This method will be executed after a successful drop action, and it's the right place for you to write the specific code that has to run as a result of the drop action.
QDrop also offers commands for customizing its behavior:
Step 3: Handle the drop action
Handling takes place inside the drop handler method that we installed using QD_SetDropHandler .
QDrop provides to the drop handler in parameter $1 the area reference on which the drop happened. Then, using two QDrop commands we get information about what was dropped on the area, in order to act accordingly.
The command QD_CountDroppedFiles will tell us how many items were dropped and then the QD_GetDroppedFile command will let us get the full path of each dropped item. Both these commands are specialized to work inside drop handler methods.
Here is how a typical drop handler method looks like:
`Sample drop handler method
|