]>
Commit | Line | Data |
---|---|---|
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 | \pythonnote{wxPython uses wxGenericDragImage on all platforms, but | |
11 | uses the wxDragImage name.} | |
12 | ||
13 | To use this class, when you wish to start dragging an image, create a wxDragImage | |
14 | object and store it somewhere you can access it as the drag progresses. | |
15 | Call BeginDrag to start, and EndDrag to stop the drag. To move the image, | |
16 | initially call Show and then Move. If you wish to update the screen contents | |
17 | during the drag (for example, highlight an item as in the dragimag sample), first call Hide, | |
18 | update the screen, call Move, and then call Show. | |
19 | ||
20 | You can drag within one window, or you can use full-screen dragging | |
21 | either across the whole screen, or just restricted to one area | |
22 | of the screen to save resources. If you want the user to drag between | |
23 | two windows, then you will need to use full-screen dragging. | |
24 | ||
25 | If you wish to draw the image yourself, use wxGenericDragImage and | |
26 | override \helpref{wxDragImage::DoDrawImage}{wxdragimagedodrawimage} and | |
27 | \helpref{wxDragImage::GetImageRect}{wxdragimagegetimagerect}. | |
28 | ||
29 | Please see {\tt samples/dragimag} for an example. | |
30 | ||
31 | \wxheading{Derived from} | |
32 | ||
33 | \helpref{wxObject}{wxobject} | |
34 | ||
35 | \wxheading{Include files} | |
36 | ||
37 | <wx/dragimag.h>\\ | |
38 | <wx/generic/dragimgg.h> | |
39 | ||
40 | \latexignore{\rtfignore{\wxheading{Members}}} | |
41 | ||
42 | \membersection{wxDragImage::wxDragImage}\label{wxdragimageconstr} | |
43 | ||
44 | \func{}{wxDragImage}{\void} | |
45 | ||
46 | Default constructor. | |
47 | ||
48 | \func{}{wxDragImage}{\param{const wxBitmap\& }{image}, \param{const wxCursor\& }{cursor = wxNullCursor}, | |
49 | \param{const wxPoint& }{hotspot = wxPoint(0, 0)}} | |
50 | ||
51 | Constructs a drag image from a bitmap and optional cursor. | |
52 | ||
53 | \func{}{wxDragImage}{\param{const wxIcon\& }{image}, \param{const wxCursor\& }{cursor = wxNullCursor}, | |
54 | \param{const wxPoint& }{hotspot = wxPoint(0, 0)}} | |
55 | ||
56 | Constructs a drag image from an icon and optional cursor. | |
57 | ||
58 | \pythonnote{This constructor is called wxDragIcon in wxPython.} | |
59 | ||
60 | \func{}{wxDragImage}{\param{const wxString\& }{text}, \param{const wxCursor\& }{cursor = wxNullCursor}, | |
61 | \param{const wxPoint& }{hotspot = wxPoint(0, 0)}} | |
62 | ||
63 | Constructs a drag image from a text string and optional cursor. | |
64 | ||
65 | \pythonnote{This constructor is called wxDragString in wxPython.} | |
66 | ||
67 | \func{}{wxDragImage}{\param{const wxTreeCtrl\& }{treeCtrl}, \param{wxTreeItemId\& }{id}} | |
68 | ||
69 | Constructs a drag image from the text in the given tree control item, and optional cursor. | |
70 | ||
71 | \pythonnote{This constructor is called wxDragTreeItem in wxPython.} | |
72 | ||
73 | \func{}{wxDragImage}{\param{const wxListCtrl\& }{treeCtrl}, \param{long }{id}} | |
74 | ||
75 | Constructs a drag image from the text in the given tree control item, and optional cursor. | |
76 | ||
77 | \pythonnote{This constructor is called wxDragListItem in wxPython.} | |
78 | ||
79 | \func{}{wxDragImage}{\param{const wxCursor\& }{cursor = wxNullCursor}, | |
80 | \param{const wxPoint& }{hotspot = wxPoint(0, 0)}} | |
81 | ||
82 | Constructs a drag image an optional cursor. This constructor is only available for | |
83 | wxGenericDragImage, and can be used when the application | |
84 | supplies \helpref{wxDragImage::DoDrawImage}{wxdragimagedodrawimage} and \helpref{wxDragImage::GetImageRect}{wxdragimagegetimagerect}. | |
85 | ||
86 | \wxheading{Parameters} | |
87 | ||
88 | \docparam{image}{Icon or bitmap to be used as the drag image. The bitmap can | |
89 | have a mask.} | |
90 | ||
91 | \docparam{text}{Text used to construct a drag image.} | |
92 | ||
93 | \docparam{cursor}{Optional cursor to combine with the image.} | |
94 | ||
95 | \docparam{hotspot}{Position of the hotspot within the new image.} | |
96 | ||
97 | \docparam{treeCtrl}{Tree control for constructing a tree drag image.} | |
98 | ||
99 | \docparam{listCtrl}{List control for constructing a list drag image.} | |
100 | ||
101 | \docparam{id}{Tree or list control item id.} | |
102 | ||
103 | \membersection{wxDragImage::BeginDrag}\label{wxdragimagebegindrag} | |
104 | ||
105 | \func{bool}{BeginDrag}{\param{const wxPoint\& }{hotspot}, \param{wxWindow* }{window}, \param{bool}{ fullScreen = FALSE}, \param{wxRect*}{ rect = NULL}} | |
106 | ||
107 | Start dragging the image, in a window or full screen. | |
108 | ||
109 | \func{bool}{BeginDrag}{\param{const wxPoint\& }{hotspot}, \param{wxWindow* }{window}, \param{wxWindow*}{ boundingWindow}} | |
110 | ||
111 | Start dragging the image, using the first window to capture the mouse and the second | |
112 | to specify the bounding area. This form is equivalent to using the first form, | |
113 | but more convenient than working out the bounding rectangle explicitly. | |
114 | ||
115 | You need to then call \helpref{wxDragImage::Show}{wxdragimageshow} | |
116 | and \helpref{wxDragImage::Move}{wxdragimagemove} to show the image on the screen. | |
117 | ||
118 | Call \helpref{wxDragImage::EndDrag}{wxdragimageenddrag} when the drag has finished. | |
119 | ||
120 | Note that this call automatically calls CaptureMouse. | |
121 | ||
122 | \wxheading{Parameters} | |
123 | ||
124 | \docparam{hotspot}{The location of the drag position relative to the upper-left corner | |
125 | of the image.} | |
126 | ||
127 | \docparam{window}{The window that captures the mouse, and within which the dragging | |
128 | is limited unless {\it fullScreen} is TRUE.} | |
129 | ||
130 | \docparam{boundingWindow}{In the second form of the function, specifies the | |
131 | area within which the drag occurs.} | |
132 | ||
133 | \docparam{fullScreen}{If TRUE, specifies that the drag will be visible over the full | |
134 | screen, or over as much of the screen as is specified by {\it rect}. Note that the mouse will | |
135 | still be captured in {\it window}.} | |
136 | ||
137 | \docparam{rect}{If non-NULL, specifies the rectangle (in screen coordinates) that | |
138 | bounds the dragging operation. Specifying this can make the operation more efficient | |
139 | by cutting down on the area under consideration, and it can also make a visual difference | |
140 | since the drag is clipped to this area.} | |
141 | ||
142 | \membersection{wxDragImage::DoDrawImage}\label{wxdragimagedodrawimage} | |
143 | ||
144 | \func{virtual bool}{DoDrawImage}{\param{wxDC\&}{ dc}, \param{const wxPoint\&}{ pos}} | |
145 | ||
146 | Draws the image on the device context with top-left corner at the given position. | |
147 | ||
148 | This function is only available with wxGenericDragImage, to allow applications to | |
149 | draw their own image instead of using an actual bitmap. If you override this function, | |
150 | you must also override \helpref{wxDragImage::GetImageRect}{wxdragimagegetimagerect}. | |
151 | ||
152 | \membersection{wxDragImage::EndDrag}\label{wxdragimageenddrag} | |
153 | ||
154 | \func{bool}{EndDrag}{\void} | |
155 | ||
156 | Call this when the drag has finished. | |
157 | ||
158 | Note that this call automatically calls ReleaseMouse. | |
159 | ||
160 | \membersection{wxDragImage::GetImageRect}\label{wxdragimagegetimagerect} | |
161 | ||
162 | \constfunc{virtual wxRect}{GetImageRect}{\param{const wxPoint\&}{ pos}} | |
163 | ||
164 | Returns the rectangle enclosing the image, assuming that the image is drawn with its | |
165 | top-left corner at the given point. | |
166 | ||
167 | This function is available in wxGenericDragImage only, and may be overridden (together with | |
168 | \helpref{wxDragImage::DoDrawImage}{wxdragimagedodrawimage}) to provide a virtual drawing capability. | |
169 | ||
170 | \membersection{wxDragImage::Hide}\label{wxdragimagehide} | |
171 | ||
172 | \func{bool}{Hide}{\void} | |
173 | ||
174 | Hides the image. You may wish to call this before updating the window | |
175 | contents (perhaps highlighting an item). Then call \helpref{wxDragImage::Move}{wxdragimagemove} | |
176 | and \helpref{wxDragImage::Show}{wxdragimageshow}. | |
177 | ||
178 | \membersection{wxDragImage::Move}\label{wxdragimagemove} | |
179 | ||
180 | \func{bool}{Move}{\param{const wxPoint\& }{pt}} | |
181 | ||
182 | Call this to move the image to a new position. The image will only be shown if | |
183 | \helpref{wxDragImage::Show}{wxdragimageshow} has been called previously (for example | |
184 | at the start of the drag). | |
185 | ||
186 | {\it pt} is the position in window coordinates (or screen coordinates if no | |
187 | window was specified to BeginDrag. | |
188 | ||
189 | You can move the image either when the image is hidden or shown, but in general dragging | |
190 | will be smoother if you move the image when it is shown. | |
191 | ||
192 | \membersection{wxDragImage::Show}\label{wxdragimageshow} | |
193 | ||
194 | \func{bool}{Show}{\void} | |
195 | ||
196 | Shows the image. Call this at least once when dragging. | |
197 | ||
198 | \membersection{wxDragImage::UpdateBackingFromWindow}\label{wxdragimageupdatebackingfromwindow} | |
199 | ||
200 | \constfunc{bool}{UpdateBackingFromWindow}{\param{wxDC\&}{ windowDC}, \param{wxMemoryDC\&}{ destDC}, | |
201 | \param{const wxRect\&}{ sourceRect}, \param{const wxRect\&}{ destRect}} | |
202 | ||
203 | Override this if you wish to draw the window contents to the backing bitmap | |
204 | yourself. This can be desirable if you wish to avoid flicker by not having to | |
205 | redraw the updated window itself just before dragging, which can cause a flicker just | |
206 | as the drag starts. Instead, paint the drag image's backing bitmap to show the appropriate | |
207 | graphic {\it minus the objects to be dragged}, and leave the window itself to be updated | |
208 | by the drag image. This can provide eerily smooth, flicker-free drag behaviour. | |
209 | ||
210 | The default implementation copies the window contents to the backing bitmap. A new | |
211 | implementation will normally copy information from another source, such as from its | |
212 | own backing bitmap if it has one, or directly from internal data structures. | |
213 | ||
214 | This function is available in wxGenericDragImage only. | |
215 |