QDrop v1.1x |
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 types, 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 type of the file being dragged. A list of acceptable file types is mandatory.
Configuring acceptable file types
You will use the command QD_SetDroppableFileTypes. Prepare an array of the file types that you want the area to accept, then associate the array with the area reference. Speaking of file types we mean MacOS 4-character filetypes, such as "TEXT", "PICT", "TIFF", "WDBN", etc.
On Windows filetypes do not exist, so file extensions have to be mapped to MacOS file types. The association of Windows extensions to MacOS filetypes is done with 4D's MAP FILE TYPES command. Keep in mind that an association cannot be changed or deleted within a single work session. If you need to change a mapping while developing and debugging a 4D application, reopen the database and remap the file extension.
The simplest cases
Configure QDrop for a few individually declared filetypes. The example below configures QDrop to accept files of types "TEXT" and "PICT" and declares the associations with Windows extensions:
C_LONGINT($error) ARRAY STRING(15;$fileTypes;2)
|
These are not real filetypes. 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 filetypes (PICT, TIFF, JPEG, GIFf, 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_folderMagic
): folders
qd_QTImageMagic
): movies supported by QuickTime
qd_QTImageMagic
): 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. |
Other configurations
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
|