************
wx.DragImage
************

Inheritance diagram for `wx.DragImage`:

|

.. inheritance-diagram:: wx.DragImage

|

Description
===========

This class is used when you wish to drag an object on the screen, and a simple cursor is not enough.
On Windows, the WIN32 API is used to do achieve smooth dragging. On other platforms, `wx.GenericDragImage` 
is used. Applications may also prefer to use `wx.GenericDragImage` on Windows, too.

.. note:: **wxPython note:** wxPython uses `wx.GenericDragImage` on all platforms, but uses the `wx.DragImage` name.

To use this class, when you wish to start dragging an image, create a `wx.DragImage` object and store it 
somewhere you can access it as the drag progresses. Call `BeginDrag <#BeginDrag>`_ to start, and `EndDrag <#EndDrag>`_ to stop the drag. 

To move the image, initially call `Show <#Show>`_ and then `Move <#Move>`_. If you wish to update the screen 
contents during the drag (for example, highlight an item as in the dragimag sample), first call `Hide <#Hide>`_, 
update the screen, call `Move <#Move>`_, and then call `Show <#Show>`_.

You can drag within one window, or you can use full-screen dragging either across the whole screen, or just 
restricted to one area of the screen to save resources. If you want the user to drag between two windows, 
then you will need to use full-screen dragging.

If you wish to draw the image yourself, use `wx.GenericDragImage` and override `DoDrawImage <#DoDrawImage>`_ 
and `GetImageRect <#GetImageRect>`_.


Derived From
^^^^^^^^^^^^^

* `wx.Object <wx.Object.html>`_ 


Methods Summary
^^^^^^^^^^^^^^^

* `__init__ <#__init__>`_ 
* `BeginDrag <#BeginDrag>`_ 
* `BeginDragBounded <#BeginDragBounded>`_ 
* `DoDrawImage <#DoDrawImage>`_ 
* `EndDrag <#EndDrag>`_ 
* `GetImageRect <#GetImageRect>`_ 
* `Hide <#Hide>`_ 
* `Move <#Move>`_ 
* `RedrawImage <#RedrawImage>`_ 
* `SetBackingBitmap <#SetBackingBitmap>`_ 
* `Show <#Show>`_ 
* `UpdateBackingFromWindow <#UpdateBackingFromWindow>`_ 

Properties Summary
^^^^^^^^^^^^^^^^^^

* `ImageRect <#ImageRect>`_ 

Class API
=========

Methods
^^^^^^^

.. method:: __init__(image, cursor=wx.NullCursor)

   Constructor.

   **Parameters:**

   * `image` (`wx.Bitmap <wx.Bitmap.html>`_)
   * `cursor` (`wx.Cursor <wx.Cursor.html>`_)

   |

   **Returns:**

   `wx.DragImage <wx.DragImage.html>`_
 

--------

.. method:: BeginDrag(hotspot, window, fullScreen=None, rect=None)

   Start dragging the image, using the first window to capture the mouse and the second to specify the 
   bounding area.

   You need to then call `Show <#Show>`_ and `Move <#Move>`_ to show the image on the screen.
   Call `EndDrag <#EndDrag>`_ when the drag has finished.

   **Parameters:**

   * `hotspot` (`wx.Point <wx.Point.html>`_): The location of the drag position relative to the upper-left corner of the image.
   * `window` (`wx.Window <wx.Window.html>`_): The window that captures the mouse, and within which the dragging is limited 
     unless `fullScreen` is ``True``.
   * `fullScreen` (int): If ``True``, specifies that the drag will be visible over the full screen, or over as much of the 
     screen as is specified by `rect`. Note that the mouse will still be captured in `window`.
   * `rect` (`wx.Rect <wx.Rect.html>`_) 

   |  

   **Returns:**

   `bool` 

.. note:: Note that this call automatically calls `wx.Window.CaptureMouse <wx.Window.html#CaptureMouse>`_.

--------

.. method:: BeginDragBounded(hotspot, window, boundingWindow)

   |
   
   **Parameters:**

   * `hotspot` (`wx.Point <wx.Point.html>`_)
   * `window` (`wx.Window <wx.Window.html>`_)
   * `boundingWindow` (`wx.Window <wx.Window.html>`_)

   |

   **Returns:**

   `bool` 

--------

.. method:: DoDrawImage(dc, pos)

   Draws the image on the device context with top-left corner at the given position.
   
   If you override this function, you must also override `GetImageRect <#GetImageRect>`_.

   **Parameters:**

   * `dc` (`wx.DC <wx.DC.html>`_) 
   * `pos` (`wx.Point <wx.Point.html>`_) 

   |  

   **Returns:**

   `bool` 

--------

.. method:: EndDrag()

   Call this when the drag has finished.

   |  

   **Returns:**

   `bool` 

.. note:: Note that this call automatically calls `wx.Window.ReleaseMouse <wx.Window.html#ReleaseMouse>`_.

--------

.. method:: GetImageRect(pos)

   Returns the rectangle enclosing the image, assuming that the image is drawn with its top-left corner at the given point.

   This function may be overridden (together with `DoDrawImage <#DoDrawImage>`_) to provide a virtual drawing capability.

   **Parameters:**

   * `pos` (`wx.Point <wx.Point.html>`_) 

   |  

   **Returns:**

   `wx.Rect <wx.Rect.html>`_
 

--------

.. method:: Hide()

   Hides the image. You may wish to call this before updating the window contents (perhaps highlighting an item). 
   Then call `Move <#Move>`_ and `Show <#Show>`_.

   |  

   **Returns:**

   `bool` 

--------

.. method:: Move(pt)

   Call this to move the image to a new position. The image will only be shown if `Show <#Show>`_ 
   has been called previously (for example at the start of the drag).

   `pt` is the position in client coordinates (relative to the window specified in `BeginDrag <#BeginDrag>`_).

   You can move the image either when the image is hidden or shown, but in general dragging will 
   be smoother if you move the image when it is shown.

   **Parameters:**

   * `pt` (`wx.Point <wx.Point.html>`_) 

   |  

   **Returns:**

   `bool` 

--------

.. method:: RedrawImage(oldPos, newPos, eraseOld, drawNew)
   
   |
   
   **Parameters:**

   * `oldPos` (`wx.Point <wx.Point.html>`_)
   * `newPos` (`wx.Point <wx.Point.html>`_)
   * `eraseOld` (bool)
   * `drawNew` (bool)

   |

   **Returns:**

   `bool` 

--------

.. method:: SetBackingBitmap(bitmap)

   |
   
   **Parameters:**

   * `bitmap` (`wx.Bitmap <wx.Bitmap.html>`_)


--------

.. method:: Show()

   Shows the image. Call this at least once when dragging.

   |  

   **Returns:**

   `bool` 

--------

.. method:: UpdateBackingFromWindow(windowDC, destDC, sourceRect, destRect)

   Override this if you wish to draw the window contents to the backing bitmap yourself. This can be desirable 
   if you wish to avoid flicker by not having to redraw the updated window itself just before dragging, which 
   can cause a flicker just as the drag starts. Instead, paint the drag image's backing bitmap to show the 
   appropriate graphic **minus the objects to be dragged**, and leave the window itself to be updated by the drag 
   image. This can provide eerily smooth, flicker-free drag behaviour.

   The default implementation copies the window contents to the backing bitmap. A new implementation will normally 
   copy information from another source, such as from its own backing bitmap if it has one, or directly from internal 
   data structures.

   **Parameters:**

   * `windowDC` (`wx.DC <wx.DC.html>`_) 
   * `destDC` (`wx.MemoryDC <wx.MemoryDC.html>`_) 
   * `sourceRect` (`wx.Rect <wx.Rect.html>`_) 
   * `destRect` (`wx.Rect <wx.Rect.html>`_) 

   |  

   **Returns:**

   `bool` 

--------

Properties
^^^^^^^^^^


.. attribute:: ImageRect

   See `GetImageRect <#GetImageRect>`_