docs/latex/wx/dragimag.tex

   1 \section{\class{wxDragImage}}\label{wxdragimage}
   2
   3 This class is used when you wish to drag an object on the screen,
   4 and a simple cursor is not enough.
   5
   6 On Windows, the WIN32 API is used to do achieve smooth dragging. On other platforms,
   7 wxGenericDragImage is used. Applications may also prefer to use
   8 wxGenericDragImage on Windows, too.
   9
  10 To use this class, when you wish to start dragging an image, create a wxDragImage
  11 object and store it somewhere you can access it as the drag progresses.
  12 Call BeginDrag to start, and EndDrag to stop the drag. To move the image,
  13 initially call Show and then Move. If you wish to update the screen contents
  14 during the drag (for example, highlight an item as in the dragimag sample), first call Hide,
  15 update the screen, call Move, and then call Show.
  16
  17 You can drag within one window, or you can use full-screen dragging
  18 either across the whole screen, or just restricted to one area
  19 of the screen to save resources. If you want the user to drag between
  20 two windows, then you will need to use full-screen dragging.
  21
  22 Please see {\tt samples/dragimag} for an example.
  23
  24 \wxheading{Derived from}
  25
  26 \helpref{wxObject}{wxobject}
  27
  28 \wxheading{Include files}
  29
  30 <wx/dragimag.h>\\
  31 <wx/generic/dragimgg.h>
  32
  33 \latexignore{\rtfignore{\wxheading{Members}}}
  34
  35 \membersection{wxDragImage::wxDragImage}\label{wxdragimageconstr}
  36
  37 \func{}{wxDragImage}{\void}
  38
  39 Default constructor.
  40
  41 \func{}{wxDragImage}{\param{const wxBitmap\& }{image}, \param{const wxCursor\& }{cursor = wxNullCursor},
  42  \param{const wxPoint& }{hotspot = wxPoint(0, 0)}}
  43
  44 Constructs a drag image from a bitmap and optional cursor.
  45
  46 \func{}{wxDragImage}{\param{const wxIcon\& }{image}, \param{const wxCursor\& }{cursor = wxNullCursor},
  47  \param{const wxPoint& }{hotspot = wxPoint(0, 0)}}
  48
  49 Constructs a drag image from an icon and optional cursor.
  50
  51 \func{}{wxDragImage}{\param{const wxString\& }{text}, \param{const wxCursor\& }{cursor = wxNullCursor},
  52  \param{const wxPoint& }{hotspot = wxPoint(0, 0)}}
  53
  54 Constructs a drag image from a text string and optional cursor.
  55
  56 \func{}{wxDragImage}{\param{const wxTreeCtrl\& }{treeCtrl}, \param{wxTreeItemId\& }{id}}
  57
  58 Constructs a drag image from the text in the given tree control item, and optional cursor.
  59
  60 \func{}{wxDragImage}{\param{const wxListCtrl\& }{treeCtrl}, \param{long }{id}}
  61
  62 Constructs a drag image from the text in the given tree control item, and optional cursor.
  63
  64 \wxheading{Parameters}
  65
  66 \docparam{image}{Icon or bitmap to be used as the drag image. The bitmap can
  67 have a mask.}
  68
  69 \docparam{text}{Text used to construct a drag image.}
  70
  71 \docparam{cursor}{Optional cursor to combine with the image.}
  72
  73 \docparam{hotspot}{Position of the hotspot within the new image.}
  74
  75 \docparam{treeCtrl}{Tree control for constructing a tree drag image.}
  76
  77 \docparam{listCtrl}{List control for constructing a list drag image.}
  78
  79 \docparam{id}{Tree or list control item id.}
  80
  81 \membersection{wxDragImage::BeginDrag}\label{wxdragimagebegindrag}
  82
  83 \func{bool}{BeginDrag}{\param{const wxPoint\& }{hotspot}, \param{wxWindow* }{window}, \param{bool}{ fullScreen = FALSE}, \param{wxRect*}{ rect = NULL}}
  84
  85 Start dragging the image, in a window or full screen.
  86
  87 \func{bool}{BeginDrag}{\param{const wxPoint\& }{hotspot}, \param{wxWindow* }{window}, \param{wxWindow*}{ boundingWindow}}
  88
  89 Start dragging the image, using the first window to capture the mouse and the second
  90 to specify the bounding area. This form is equivalent to using the first form,
  91 but more convenient than working out the bounding rectangle explicitly.
  92
  93 You need to then call \helpref{wxDragImage::Show}{wxdragimageshow}
  94 and \helpref{wxDragImage::Move}{wxdragimagemove} to show the image on the screen.
  95
  96 Call \helpref{wxDragImage::EndDrag}{wxdragimageenddrag} when the drag has finished.
  97
  98 Note that this call automatically calls CaptureMouse.
  99
 100 \wxheading{Parameters}
 101
 102 \docparam{hotspot}{The location of the drag position relative to the upper-left corner
 103 of the image.}
 104
 105 \docparam{window}{The window that captures the mouse, and within which the dragging
 106 is limited unless {\it fullScreen} is TRUE.}
 107
 108 \docparam{boundingWindow}{In the second form of the function, specifies the
 109 area within which the drag occurs.}
 110
 111 \docparam{fullScreen}{If TRUE, specifies that the drag will be visible over the full
 112 screen, or over as much of the screen as is specified by {\it rect}. Note that the mouse will
 113 still be captured in {\it window}.}
 114
 115 \docparam{rect}{If non-NULL, specifies the rectangle (in screen coordinates) that
 116 bounds the dragging operation. Specifying this can make the operation more efficient
 117 by cutting down on the area under consideration, and it can also make a visual difference
 118 since the drag is clipped to this area.}
 119
 120 \membersection{wxDragImage::EndDrag}\label{wxdragimageenddrag}
 121
 122 \func{bool}{EndDrag}{\void}
 123
 124 Call this when the drag has finished.
 125
 126 Note that this call automatically calls ReleaseMouse.
 127
 128 \membersection{wxDragImage::Hide}\label{wxdragimagehide}
 129
 130 \func{bool}{Hide}{\void}
 131
 132 Hides the image. You may wish to call this before updating the window
 133 contents (perhaps highlighting an item). Then call \helpref{wxDragImage::Move}{wxdragimagemove}
 134 and \helpref{wxDragImage::Show}{wxdragimageshow}.
 135
 136 \membersection{wxDragImage::Move}\label{wxdragimagemove}
 137
 138 \func{bool}{Move}{\param{const wxPoint\& }{pt}}
 139
 140 Call this to move the image to a new position. The image will only be shown if
 141 \helpref{wxDragImage::Show}{wxdragimageshow} has been called previously (for example
 142 at the start of the drag).
 143
 144 {\it pt} is the position in window coordinates (or screen coordinates if no
 145 window was specified to BeginDrag.
 146
 147 You can move the image either when the image is hidden or shown, but in general dragging
 148 will be smoother if you move the image when it is shown.
 149
 150 \membersection{wxDragImage::Show}\label{wxdragimageshow}
 151
 152 \func{bool}{Show}{\void}
 153
 154 Shows the image. Call this at least once when dragging.
 155