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