Called to complete a successful drop operation.

This handler is only called if both the prepare drop and drop event handlers were successful. You can use this handler, for example, to clean up any state that was set or changed in the prepare drop handler.

The drop handler is the only required handler for supporting dropped data in AppleScript Studio.

Both the text view and text field classes have built-in support for dropped text, provided automatically by the Cocoa classes they are based on (NSTextView and NSTextField). If that’s all the support for dropped text your application needs for objects of these types, you don’t need to do anything extra. However, an application that wants to handle data that is dropped on a text view or a text field, and not allow the default support to handle it, should take these steps:

• register the drag types the text view or text field can handle; see the register command for details

• connect a drop handler to handle dropped text for the text view or text field

• connect an empty conclude drop handler for the text view or text field; this will prevent the text objects from providing their own support for dropped text

Syntax

Parameters

reference

a reference to the object whose conclude drop handler is called

drag info  drag info

the information about the drag operation

Examples

When you connect a conclude drop handler to an object in Interface Builder, AppleScript Studio supplies an empty handler template. Your handler can take any necessary steps to deal with the conclusion of the drop that it didn’t take care of in its drop handler. For example, the handler might clean up any state that was set or changed in the prepare drop handler.

on conclude drop theObject drag info dragInfo

    (* Statements to deal with the concluded drop. *)

end conclude drop

See also the description above for this class.

Version Notes

The conclude drop event handler was added in AppleScript Studio version 1.2.

Not supported (through AppleScript Studio version 1.4).

Support for this event handler is planned for a later version of AppleScript Studio.

Syntax

Parameters

reference

a reference to the object whose drag handler is called

drag info  drag info

the information about the drag operation

Version Notes

The drag event handler was added in AppleScript Studio version 1.2, although it does nothing in that version.

Called when a user drags the registered type of data into the bounds of the object.

Your application may not need a drag entered handler, as the drop handler is the only required handler for supporting dropped data in AppleScript Studio.

Syntax

Parameters

reference

a reference to the object whose drag entered handler is called

drag info  drag info

the information about the drag operation

Examples

When you connect a drag entered handler to an object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the object for which a potential drag has entered the object’s bounds. The dragInfo parameter provides access to a drag info object that contains all pertinent information for the drag operation. Your handler can take any necessary steps, such as providing visual feedback that it can accept information from the drag.

on drag entered theObject drag info dragInfo

    (* Statements to deal with the drag entering. *)

end drag entered

Version Notes

The drag entered event handler was added in AppleScript Studio version 1.2.

Called when a user drags the registered type of data out of the bounds of the object.

Your application may not need a drag exited handler, as the drop handler is the only required handler for supporting dropped data in AppleScript Studio.

Syntax

Parameters

reference

a reference to the object whose drag exited handler is called

drag info  drag info

the information about the drag operation

Examples

When you connect a drag exited handler to an object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the object for which a potential drag has exited the object’s bounds. The dragInfo parameter provides access to a drag info object that contains all pertinent information for the drag operation. Your handler can take any necessary steps, such as providing visual feedback that it is no longer waiting to accept information from the drag.

on drag exited theObject drag info dragInfo

    (* Statements to deal with the drag exiting. *)

end drag exited

Version Notes

The drag exited event handler was added in AppleScript Studio version 1.2.

Called when a user moves a registered drag type within the bounds of the object.

Your application may not need a drag updated handler, as the drop handler is the only required handler for supporting dropped data in AppleScript Studio.

Syntax

Parameters

reference

a reference to the object whose drag updated handler is called

drag info  drag info

the information about the drag operation

Examples

When you connect a drag updated handler to an object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the object in whose bounds a drag with a registered type has moved. The dragInfo parameter provides access to a drag info object that contains all pertinent information for the drag operation. Your handler can take any necessary steps, such as providing visual feedback as to where the drag data might be inserted. Note however, that through AppleScript Studio version 1.3, you cannot access the location property of a drag info object, so the ability to determine an insertion point is limited.

on drag updated theObject drag info dragInfo

    (* Statements to deal with the drag updating. *)

end drag updated

Version Notes

The drag updated event handler was added in AppleScript Studio version 1.2.

Called when a user has dropped data with a registered data type onto an object.

You return false from this event handler to cancel the drop operation; otherwise you must return true to signal success for the drop operation.

You can examine the pasteboard property of the drag info parameter to obtain the data for the drop in the requested format. If you use the prepare drop handler to verify that the data you need is present, you will know that data is available when the drop handler is called.

The drop handler is the only required handler for supporting dropped data in AppleScript Studio. However, see the conclude drop event handler for information on providing drag and drop for text view and text field objects.

Syntax

Parameters

reference

a reference to the object whose handler is called to receive the dropped data

drag info  drag info

the information about the drag operation

Examples

The Drag and Drop sample application (distributed with AppleScript Studio, starting with version 1.2) demonstrates how various objects can accept dragged data. The following drop handler, from the file Text.applescript in that application, shows how to accept dragged text data in a text field.

The drop event handler is called when the appropriate type of data is dropped onto the object. All of the pertinent information about the drop is contained in the drag info object (passed in the drag info parameter). In this case, the handler just checks the pasteboard of the drag info object for the “string” data type. If it is present, the handler uses it to set the contents of the passed text field (from the theObject parameter).

on drop theObject drag info dragInfo

    -- We are only interested in the "string" data type

        -- If that type is present, set the contents of the text

        --  field to the contents of the pasteboard

    if "string" is in types of pasteboard of dragInfo  then

        set string value of theObject to contents of pasteboard  of dragInfo

    end if

    return true

end drop

By default, the preferred type property for a pasteboard is “string”, which is why the handler above doesn’t set the preferred type. To explicitly set the preferred type of a pasteboard (in this example, the “general” pasteboard) to “string” before getting data from the pasteboard, you could use the following statements:

set preferred type of pasteboard "general" to "string"

if "string" is in types of pasteboard "general"  then

    set myString to contents of pasteboard "general"

Version Notes

The drop event handler was added in AppleScript Studio version 1.2.

Called when a user has dropped the dragged data onto the object.

You return false from this event handler to cancel the drop operation; otherwise you must return true to continue the drop operation.

You can examine the pasteboard property of the drag info parameter to determine, for example, whether it contains data in the format you want.

Your application may not need a prepare drop handler, as the drop handler is the only required handler for supporting dropped data in AppleScript Studio.

Syntax

Parameters

reference

a reference to the object whose handler is called

drag info  drag info

the information about the drag operation

Examples

When you connect a prepare drop handler to an object in Interface Builder, AppleScript Studio supplies an empty handler template. The theObject parameter refers to the object for which a drop is about to take place. The dragInfo parameter provides access to a drag info object that contains all pertinent information for the drag operation. Your handler can do any necessary preparation, such as making sure the necessary data is present for the drop operation to take place. The handler should return false to cancel the drop operation or true to allow it.

on prepare drop theObject drag info dragInfo

    (* Statements to prepare for a drop.

        In this example, only allow drop if string info available.  *)

    if "string" is in types of pasteboard of dragInfo  then

        return true

    else

        return false

    end if

end prepare drop

Version Notes

The prepare drop event handler was added in AppleScript Studio version 1.2.