gtk.gdk.DragContext
Prev | The gtk.gdk Class Reference | Next

## gtk.gdk.DragContext

gtk.gdk.DragContext — an object containing the drag and drop context data

## Synopsis

    class gtk.gdk.DragContext(gobject.GObject):
        gtk.gdk.DragContext()
        def drag_status(action, time)
        def drop_reply(ok, time)
        def drop_finish(success, time)
        def drag_get_selection()
        def drag_find_window(drag_window, x_root, y_root)
        def drag_find_window_for_screen(drag_window, screen, x_root, y_root)
        def drag_motion(dest_window, protocol, x_root, y_root, suggested_action, possible_actions, time)
        def drag_drop(time)
        def drag_abort(time)
        def finish(success, del_, time)
        def get_source_widget()
        def set_icon_widget(widget, hot_x, hot_y)
        def set_icon_pixmap(colormap, pixmap, mask, hot_x, hot_y)
        def set_icon_pixbuf(pixbuf, hot_x, hot_y)
        def set_icon_stock(stock_id, hot_x, hot_y)
        def set_icon_name(icon_name, hot_x, hot_y)
        def set_icon_default()
        def drag_drop_succeeded()

## Ancestry

    +-- gobject.GObject
      +-- gtk.gdk.DragContext

## Attributes

"action" | Read | the action chosen by the destination. One of: `gtk.gdk.ACTION_COPY`, `gtk.gdk.ACTION_MOVE`, `gtk.gdk.ACTION_LINK`, `gtk.gdk.ACTION_PRIVATE`
"actions" | Read | a bitmask of actions proposed by the source when `suggested_action` is `gtk.gdk.ACTION_ASK`. A combination of: `gtk.gdk.ACTION_COPY`, `gtk.gdk.ACTION_MOVE`, `gtk.gdk.ACTION_LINK`, `gtk.gdk.ACTION_PRIVATE`
"dest_window" | Read | the destination `gtk.gdk.Window` of this drag.
"is_source" | Read | if True the context is used on the source side.
"protocol" | Read | the DND protocol which governs this drag - one of: `gtk.gdk.DRAG_PROTO_MOTIF`, `gtk.gdk.DRAG_PROTO_XDND`, `gtk.gdk.DRAG_PROTO_ROOTWIN`, `gtk.gdk.DRAG_PROTO_NONE`, `gtk.gdk.DRAG_PROTO_WIN32_DROPFILES`, `gtk.gdk.DRAG_PROTO_OLE2`, `gtk.gdk.DRAG_PROTO_LOCAL`
"source_window" | Read | the source `gtk.gdk.Window` of this drag.
"start_time" | Read | a timestamp recording the start time of this drag.
"suggested_action" | Read | the action suggested by the source. One of: `gtk.gdk.ACTION_DEFAULT`, `gtk.gdk.ACTION_COPY`, `gtk.gdk.ACTION_MOVE`, `gtk.gdk.ACTION_LINK`, `gtk.gdk.ACTION_PRIVATE`, `gtk.gdk.ACTION_ASK`
"targets" | Read | a list of targets offered by the source.

## Description

A `gtk.gdk.DragContext` holds information about a drag in progress. It is used for both source and destination. A `gtk.gdk.DragContext` can be created using the gtk.gdk.DragContext() constructor but since there is no way to set its attributes the new object is not much use. Useful `gtk.gdk.DragContext` objects are created as a result of the `gtk.gdk.Window.drag_begin`() or the `gtk.Widget.drag_begin`() methods.

## Constructor

        gtk.gdk.DragContext()

Returns : | a new `gtk.gdk.DragContext`

Creates a new `gtk.gdk.DragContext` object.

## Methods

### gtk.gdk.DragContext.drag_status

        def drag_status(action, time)

`action` : | a drag action that will be taken when a drop happens
`time` : | the timestamp for this action

The `drag_status`() method sets the specified `action` to be taken when a drop happens. The value of `action` is one of:

`gtk.gdk.ACTION_DEFAULT` |
`gtk.gdk.ACTION_COPY` | Copy the data.
`gtk.gdk.ACTION_MOVE` | Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol.
`gtk.gdk.ACTION_LINK` | Add a link to the data. Note that this is only useful if source and destination agree on what it means.
`gtk.gdk.ACTION_PRIVATE` | Special action which tells the source that the destination will do something that the source doesn't understand.
`gtk.gdk.ACTION_ASK` | Ask the user what to do with the data.

The time the action occurred is specified by `time`. This method is called by the drag destination in response to `drag_motion`() called by the drag source.

### gtk.gdk.DragContext.drop_reply

        def drop_reply(ok, time)

`ok` : | if `True` the drop is accepted by the destination
`time` : | the timestamp

The `drop_reply`() method determines if the drop is accepted or rejected according to the value specified by `ok`. If `ok` is `True` the drop is accepted. `time` specifies the time that the drop reply occurred. This method is called by the drag destination when a drop is initiated by the drag source.

### gtk.gdk.DragContext.drop_finish

        def drop_finish(success, time)

`success` : | if True the data was received
`time` : | the time of the finish

The `drop_finish`() method ends a drag operation and indicates if the drop was successful by setting the value of `success`. `time` indicates the time of the drop finish. This method is called by the drag destination.

### gtk.gdk.DragContext.drag_get_selection

        def drag_get_selection()

Returns : | the selection atom

The `drag_get_selection`() method returns the selection atom for the current source window.

### gtk.gdk.DragContext.drag_find_window

        def drag_find_window(drag_window, x_root, y_root)

`drag_window` : | a `gtk.gdk.Window`
`x_root` : | the x position of the pointer in root coordinates.
`y_root` : | the y position of the pointer in root coordinates.
Returns : | a 2-tuple containing the drag destination `gtk.gdk.Window` and the drag protocol

The `drag_find_window`() method returns a 2-tuple containing the drag destination `gtk.gdk.Window` and the drag protocol being used. The drag protocol is one of:

`gtk.gdk.DRAG_PROTO_MOTIF` | The Motif DND protocol.
`gtk.gdk.DRAG_PROTO_XDND` | The Xdnd protocol.
`gtk.gdk.DRAG_PROTO_ROOTWIN` | An extension to the Xdnd protocol for unclaimed root window drops.
`gtk.gdk.DRAG_PROTO_NONE` | no protocol.
`gtk.gdk.DRAG_PROTO_WIN32_DROPFILES` | The simple WM_DROPFILES protocol.
`gtk.gdk.DRAG_PROTO_OLE2` | The complex OLE2 DND protocol (not implemented).
`gtk.gdk.DRAG_PROTO_LOCAL` | Intra-application DND.

`drag_window` is a `gtk.gdk.Window` and `x_root` and `y_root` specify the location of the mouse pointer in the root window.

### gtk.gdk.DragContext.drag_find_window_for_screen

        def drag_find_window_for_screen(drag_window, screen, x_root, y_root)

`drag_window` : | a `gtk.gdk.Window`
`screen` : | a `gtk.gdk.Screen`
`x_root` : | the x position of the pointer in root coordinates.
`y_root` : | the y position of the pointer in root coordinates.
Returns : | a 2-tuple containing the drag destination `gtk.gdk.Window` and the drag protocol

### Note

This method is available in PyGTK 2.2 and above.

The `drag_find_window_for_screen`() method returns a 2-tuple containing the drag destination `gtk.gdk.Window` and the drag protocol being used. The drag protocol is one of:

`gtk.gdk.DRAG_PROTO_MOTIF` | The Motif DND protocol.
`gtk.gdk.DRAG_PROTO_XDND` | The Xdnd protocol.
`gtk.gdk.DRAG_PROTO_ROOTWIN` | An extension to the Xdnd protocol for unclaimed root window drops.
`gtk.gdk.DRAG_PROTO_NONE` | no protocol.
`gtk.gdk.DRAG_PROTO_WIN32_DROPFILES` | The simple WM_DROPFILES protocol.
`gtk.gdk.DRAG_PROTO_OLE2` | The complex OLE2 DND protocol (not implemented).
`gtk.gdk.DRAG_PROTO_LOCAL` | Intra-application DND.

`drag_window` is a `gtk.gdk.Window` and `x_root` and `y_root` specify the location of the mouse pointer in the root window.

### gtk.gdk.DragContext.drag_motion

        def drag_motion(dest_window, protocol, x_root, y_root, suggested_action, possible_actions, time)

`dest_window` : | the destination `gtk.gdk.Window` the drag is moving over
`protocol` : | the drag protocol in use
`x_root` : | the x root coordinate of the mouse pointer
`y_root` : | the y root coordinate of the mouse pointer
`suggested_action` : | the suggest drag action
`possible_actions` : | the possible drag actions
`time` : | the timestamp of the drag motion
Returns : | True if there is a drag destination window and the drag has paused or a drop has occurred.

The `drag_motion`() method updates the drag context when the pointer moves or the set of actions changes. This method is called by the drag source. `dest_window` specifies the drag destination `gtk.gdk.Window`; `protocol` specifies the drag protocol being used (see the `drag_find_window`() method for details); `x_root` and `y_root` specify the root window coordinates of the mouse pointer; `suggested_action` specifies the suggested drag action (see the `drag_status`() method for more detail); possible_actions specifies the possible drag actions for the drag (see the `drag_status`() method for more detail); and, `time` specifies the timestamp of the drag motion.

### gtk.gdk.DragContext.drag_drop

        def drag_drop(time)

`time` : | the timestamp of the drag drop.

The `drag_drop`() method initiates a drop on the current drag destination at the time specified by `time`. This method is called by the drag source.

### gtk.gdk.DragContext.drag_abort

        def drag_abort(time)

`time` : | the time of the drag abort operation

The `drag_abort`() method aborts the current drag operation at the specified `time`. No drop operation is initiated. This method is called by the drag source.

### gtk.gdk.DragContext.finish

        def finish(success, del_, time)

`success` : | if `True` the drop was completed
`del_` : | if `True` the drag source should delete the source data
`time` : | the time of the drag finish operation.

The `finish`() method informs the drag source that the drop is finished, and that the data of the drag will no longer be required. If `success` is `True` the drag drop completed successfully; if `del_` is `True` the source data should be deleted; `time` is the timestamp of the finish operation. This method is called by the drag destination.

### gtk.gdk.DragContext.get_source_widget

        def get_source_widget()

Returns : | the source `gtk.Widget` if the drag is within the same application or `None` otherwise.

The `get_source_widget`() method returns the source `gtk.Widget` if the drag is within the application; otherwise `None` is returned.

### gtk.gdk.DragContext.set_icon_widget

        def set_icon_widget(widget, hot_x, hot_y)

`widget` : | a toplevel window to use as an icon.
`hot_x` : | the X offset within `widget` of the hotspot.
`hot_y` : | the Y offset within `widget` of the hotspot.

The `set_icon_widget`() method changes the icon for a drag source to the specified `widget` with its hot spot at the offset specified by `hot_x` and `hot_y`. `PyGTK` will not destroy the icon, so if you don't want it to persist, you should connect to the "drag_end" signal and destroy it yourself.

### gtk.gdk.DragContext.set_icon_pixmap

        def set_icon_pixmap(colormap, pixmap, mask, hot_x, hot_y)

`colormap` : | the colormap of the icon
`pixmap` : | the `gtk.gdk.Pixmap` image data for the icon
`mask` : | the `gtk.gdk.Pixmap` transparency mask for the icon
`hot_x` : | the X offset within `pixmap` of the hotspot.
`hot_y` : | the Y offset within `pixmap` of the hotspot.

The `set_icon_pixmap`() method sets `pixmap` as the icon for the drag. `mask` is a bitmap mask for `pixmap` and `hot_x` and `hot_y` specify the offset of the hot spot in `pixmap`. In general, `gtk.gdk.DragContext.set_icon_pixbuf()` will be more convenient to use.

### gtk.gdk.DragContext.set_icon_pixbuf

        def set_icon_pixbuf(pixbuf, hot_x, hot_y)

`pixbuf` : | the `gtk.gdk.Pixbuf` to use as the drag icon.
`hot_x` : | the X offset within `pixbuf` of the hotspot.
`hot_y` : | the Y offset within `pixbuf` of the hotspot.

The `set_icon_pixbuf`() method sets `pixbuf` as the icon for the drag. `hot_x` and `hot_y` specify the offset of the hot spot within `pixbuf`.

### gtk.gdk.DragContext.set_icon_stock

        def set_icon_stock(stock_id, hot_x, hot_y)

`stock_id` : | the ID of the stock icon to use for the drag.
`hot_x` : | the X offset within the icon of the hotspot.
`hot_y` : | the Y offset within the icon of the hotspot.

The `set_icon_stock`() method sets the the icon for a given drag from a stock ID specified by `stock_id`. `hot_x` and `hot_y` specify the offset of the hot spot within the stock icon.

### gtk.gdk.DragContext.set_icon_name

        def set_icon_name(icon_name, hot_x, hot_y)

`icon_name` : | the name of the icon to use for the drag.
`hot_x` : | the X offset within the icon of the hotspot.
`hot_y` : | the Y offset within the icon of the hotspot.

### Note

This method is available in PyGTK 2.10 and above.

The `set_icon_name`() method sets the the icon for a given drag from the named themed icon specified by `icon_name`. `hot_x` and `hot_y` specify the offset of the hot spot within the stock icon. See the docs for `gtk.IconTheme` for more information. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size `gtk.ICON_SIZE_DND`), thus `hot_x` and `hot_y` have to be used with care.

### gtk.gdk.DragContext.set_icon_default

        def set_icon_default()

The `set_icon_default`() method sets the icon for the drag to the default icon.

### gtk.gdk.DragContext.drag_drop_succeeded

        def drag_drop_succeeded()

Returns : | `True` if the drop was successful.

The `drag_drop_succeeded`() method returns `True` if the dropped data has been successfully transferred. This method is intended to be used while handling a `gtk.gdk.DROP_FINISHED` event, its return value is meaningless at other times.

Prev | Up | Next
gtk.gdk.DisplayManager | Home | gtk.gdk.Drawable