← Back to branch summary

~brian-sidebotham/wxwidgets-cmake/wxpython-2.9.4

« back to all changes in this revision

Viewing changes to interface/wx/dragimag.h

  • Committer: Brian Sidebotham
  • Date: 2013-08-03 14:30:08 UTC
  • Revision ID: brian.sidebotham@gmail.com-20130803143008-c7806tkych1tp6fc
Initial import into Bazaar

Show diffs side-by-side

added added

removed removed

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