/////////////////////////////////////////////////////////////////////////////
// Name: dragimag.h
-// Purpose: documentation for wxDragImage class
+// Purpose: interface of wxDragImage
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@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);
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;
};
+
projects / wxWidgets.git / blobdiff