X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/328f5751e8a06727b137189fe04891a9f43bfc8b..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/dragimag.h diff --git a/interface/dragimag.h b/interface/dragimag.h index 695c393a10..9de1317021 100644 --- a/interface/dragimag.h +++ b/interface/dragimag.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: dragimag.h -// Purpose: documentation for wxDragImage class +// Purpose: interface of wxDragImage // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,162 +10,226 @@ @class wxDragImage @wxheader{dragimag.h} - This class is used when you wish to drag an object on the screen, - and a simple cursor is not enough. + 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 achieve smooth dragging. On other - platforms, - wxGenericDragImage is used. Applications may also prefer to use + platforms, wxGenericDragImage is used. Applications may also prefer to use wxGenericDragImage on Windows, too. - @b wxPython note: wxPython uses wxGenericDragImage on all platforms, but - uses the wxDragImage name. + @beginWxPythonOnly + wxPython uses wxGenericDragImage on all platforms, but uses the wxDragImage + name. + @endWxPythonOnly To use this class, when you wish to start dragging an image, create a - wxDragImage - object and store it somewhere you can access it as the drag progresses. - Call BeginDrag to start, and EndDrag to stop the drag. To move the image, - initially call Show and then 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, - update the screen, call Move, and then call Show. + wxDragImage object and store it somewhere you can access it as the drag + progresses. Call BeginDrag() to start, and EndDrag() to stop the drag. To + move the image, initially call Show() and then 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(), update the screen, call + Move(), and then call 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. + 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 wxGenericDragImage and - override wxDragImage::DoDrawImage and - wxDragImage::GetImageRect. - - Please see @c samples/dragimag for an example. + If you wish to draw the image yourself, use wxGenericDragImage and override + DoDrawImage() and GetImageRect(). @library{wxcore} - @category{FIXME} + @category{dnd} + + @see @ref page_samples_dragimag */ class wxDragImage : public wxObject { public: - //@{ /** - ) - Constructs a drag image an optional cursor. This constructor is only available - for - wxGenericDragImage, and can be used when the application - supplies DoDrawImage() and GetImageRect(). - + Default constructor. + */ + wxDragImage(); + /** + Constructs a drag image from a bitmap and optional cursor. + @param image - Icon or bitmap to be used as the drag image. The bitmap can - have a mask. + Bitmap to be used as the drag image. The bitmap can have a mask. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxBitmap& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from an icon and optional cursor. + + @param image + Icon to be used as the drag image. + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragIcon in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxIcon& image, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from a text string and optional cursor. + @param text Text used to construct a drag image. @param cursor Optional cursor to combine with the image. - @param hotspot + @param cursorHotspot This parameter is deprecated. + + @beginWxPythonOnly + This constructor is called wxDragString in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxString& text, const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + /** + Constructs a drag image from the text in the given tree control item, + and optional cursor. + @param treeCtrl Tree control for constructing a tree drag image. + @param id + Tree control item id. + + @beginWxPythonOnly + This constructor is called wxDragTreeItem in wxPython. + @endWxPythonOnly + */ + wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); + /** + Constructs a drag image from the text in the given list control item, + and optional cursor. + @param listCtrl List control for constructing a list drag image. @param id - Tree or list control item id. + List control item id. + + @beginWxPythonOnly + This constructor is called wxDragListItem in wxPython. + @endWxPythonOnly */ - wxDragImage(); - wxDragImage(const wxBitmap& image, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxIcon& image, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxString& text, - const wxCursor& cursor = wxNullCursor); - wxDragImage(const wxTreeCtrl& treeCtrl, wxTreeItemId& id); - wxDragImage(const wxListCtrl& treeCtrl, long id); - wxDragImage(const wxCursor& cursor = wxNullCursor); - //@} - - //@{ - /** - Start dragging the image, using the first window to capture the mouse and the - second - to specify the bounding area. This form is equivalent to using the first form, - but more convenient than working out the bounding rectangle explicitly. - You need to then call Show() - and Move() to show the image on the screen. - Call EndDrag() when the drag has finished. - Note that this call automatically calls CaptureMouse. - + wxDragImage(const wxListCtrl& listCtrl, long id); + /** + Constructs a drag image an optional cursor. This constructor is only + available for wxGenericDragImage, and can be used when the application + supplies DoDrawImage() and GetImageRect(). + + @param cursor + Optional cursor to combine with the image. + @param cursorHotspot + This parameter is deprecated. + */ + wxDragImage(const wxCursor& cursor = wxNullCursor, + const wxPoint& cursorHotspot = wxPoint(0, 0)); + + /** + Start dragging the image, in a window or full screen. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). + @param hotspot The location of the drag position relative to the upper-left corner of the image. @param window The window that captures the mouse, and within which the dragging is limited unless fullScreen is @true. - @param boundingWindow - In the second form of the function, specifies the - area within which the drag occurs. @param fullScreen 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. + screen, or over as much of the screen as is specified by rect. Note + that the mouse will still be captured in window. @param rect If non-@NULL, specifies the rectangle (in screen coordinates) that - bounds the dragging operation. Specifying this can make the operation more - efficient - by cutting down on the area under consideration, and it can also make a - visual difference - since the drag is clipped to this area. + bounds the dragging operation. Specifying this can make the + operation more efficient by cutting down on the area under + consideration, and it can also make a visual difference since the + drag is clipped to this area. */ bool BeginDrag(const wxPoint& hotspot, wxWindow* window, - bool fullScreen = false, - wxRect* rect = NULL); + bool fullScreen = false, wxRect* rect = NULL); + /** + Start dragging the image, using the first window to capture the mouse + and the second to specify the bounding area. This form is equivalent to + using the first form, but more convenient than working out the bounding + rectangle explicitly. + + You need to then call Show() and Move() to show the image on the + screen. Call EndDrag() when the drag has finished. + + Note that this call automatically calls CaptureMouse(). + + @param hotspot + The location of the drag position relative to the upper-left corner + of the image. + @param window + The window that captures the mouse, and within which the dragging + is limited. + @param boundingWindow + Specifies the area within which the drag occurs. + */ bool BeginDrag(const wxPoint& hotspot, wxWindow* window, wxWindow* boundingWindow); - //@} /** Draws the image on the device context with top-left corner at the given position. - This function is only available with wxGenericDragImage, to allow applications - to - draw their own image instead of using an actual bitmap. If you override this - function, - you must also override GetImageRect(). + + This function is only available with wxGenericDragImage, to allow + applications to draw their own image instead of using an actual bitmap. + If you override this function, you must also override GetImageRect(). */ virtual bool DoDrawImage(wxDC& dc, const wxPoint& pos); /** Call this when the drag has finished. - Note that this call automatically calls ReleaseMouse. + + @note This function automatically releases mouse capture. */ bool EndDrag(); /** - Returns the rectangle enclosing the image, assuming that the image is drawn - with its - top-left corner at the given point. - This function is available in wxGenericDragImage only, and may be overridden - (together with - wxDragImage::DoDrawImage) to provide a virtual drawing capability. + Returns the rectangle enclosing the image, assuming that the image is + drawn with its top-left corner at the given point. + + This function is available in wxGenericDragImage only, and may be + overridden (together with DoDrawImage()) to provide a virtual drawing + capability. */ virtual wxRect GetImageRect(const wxPoint& pos) const; /** Hides the image. You may wish to call this before updating the window - contents (perhaps highlighting an item). Then call Move() - and Show(). + contents (perhaps highlighting an item). Then call Move() and Show(). */ bool Hide(); /** - Call this to move the image to a new position. The image will only be shown if - Show() has been called previously (for example - at the start of the drag). - @a pt is the position in client coordinates (relative to the window specified - in 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. + Call this to move the image to a new position. The image will only be + shown if Show() has been called previously (for example at the start of + the drag). + + @param pt + The position in client coordinates (relative to the window + specified in 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. */ bool Move(const wxPoint& pt); @@ -175,23 +239,24 @@ public: bool Show(); /** - 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 @e 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. + 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 @e 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. + This function is available in wxGenericDragImage only. */ bool UpdateBackingFromWindow(wxDC& windowDC, wxMemoryDC& destDC, const wxRect& sourceRect, const wxRect& destRect) const; }; +