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"Readthe action chosen by the destination. One of: gtk.gdk.ACTION_COPY, gtk.gdk.ACTION_MOVE, gtk.gdk.ACTION_LINK, gtk.gdk.ACTION_PRIVATE
"actions"Reada 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"Readthe destination gtk.gdk.Window of this drag.
"is_source"Readif True the context is used on the source side.
"protocol"Readthe 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"Readthe source gtk.gdk.Window of this drag.
"start_time"Reada timestamp recording the start time of this drag.
"suggested_action"Readthe 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"Reada 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.