ccba6d73f9
Fix wrong use of Doxygen grouping-related markup which somehow worked in older Doxygen versions, but doesn't work any longer. This fixes the problem with the "Functions by Category" pages being empty in the resulting HTML documentation and wrong documentation being shown for a bunch of wxString members. This is a combined cherry-pick of the following master commits: bd92523bc5 Fix use of Doxygen @addtogroup command 4c46e01b14 Remove stray Doxygen end group marker 8ac10d28f8 Fix all the other comments with Doxygen grouping commands too c0f1ecf263 Fix another unbalanced Doxygen grouping command after last commit See #22248, #22572.
456 lines
14 KiB
Objective-C
456 lines
14 KiB
Objective-C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: dnd.h
|
|
// Purpose: interface of wxDropSource and wx*DropTarget
|
|
// Author: wxWidgets team
|
|
// Licence: wxWindows licence
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/**
|
|
Possible flags for drag and drop operations.
|
|
*/
|
|
enum
|
|
{
|
|
wxDrag_CopyOnly = 0, ///< Allow only copying.
|
|
wxDrag_AllowMove = 1, ///< Allow moving too (copying is always allowed).
|
|
wxDrag_DefaultMove = 3 ///< Allow moving and make it default operation.
|
|
};
|
|
|
|
/**
|
|
Result returned from a wxDropSource::DoDragDrop() call.
|
|
*/
|
|
enum wxDragResult
|
|
{
|
|
wxDragError, ///< Error prevented the D&D operation from completing.
|
|
wxDragNone, ///< Drag target didn't accept the data.
|
|
wxDragCopy, ///< The data was successfully copied.
|
|
wxDragMove, ///< The data was successfully moved (MSW only).
|
|
wxDragLink, ///< Operation is a drag-link.
|
|
wxDragCancel ///< The operation was cancelled by user (not an error).
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxDropTarget
|
|
|
|
This class represents a target for a drag and drop operation. A
|
|
wxDataObject can be associated with it and by default, this object will be
|
|
filled with the data from the drag source, if the data formats supported by
|
|
the data object match the drag source data format.
|
|
|
|
There are various virtual handler functions defined in this class which may
|
|
be overridden to give visual feedback or react in a more fine-tuned way,
|
|
e.g. by not accepting data on the whole window area, but only a small
|
|
portion of it. The normal sequence of calls is OnEnter(), OnDragOver()
|
|
possibly many times, OnDrop() and finally OnData().
|
|
|
|
@library{wxcore}
|
|
@category{dnd}
|
|
|
|
@see @ref overview_dnd, @ref overview_dataobject, wxDropSource,
|
|
wxTextDropTarget, wxFileDropTarget, wxDataFormat, wxDataObject
|
|
*/
|
|
class wxDropTarget
|
|
{
|
|
public:
|
|
/**
|
|
Constructor. @a data is the data to be associated with the drop target.
|
|
*/
|
|
wxDropTarget(wxDataObject* data = NULL);
|
|
|
|
/**
|
|
Destructor. Deletes the associated data object, if any.
|
|
*/
|
|
virtual ~wxDropTarget();
|
|
|
|
/**
|
|
This method may only be called from within OnData(). By default, this
|
|
method copies the data from the drop source to the wxDataObject
|
|
associated with this drop target, calling its wxDataObject::SetData()
|
|
method.
|
|
*/
|
|
virtual bool GetData();
|
|
|
|
/**
|
|
Called after OnDrop() returns @true. By default this will usually
|
|
GetData() and will return the suggested default value @a defResult.
|
|
*/
|
|
virtual wxDragResult OnData(wxCoord x, wxCoord y, wxDragResult defResult) = 0;
|
|
|
|
/**
|
|
Called when the mouse is being dragged over the drop target. By
|
|
default, this calls functions return the suggested return value @a defResult.
|
|
|
|
@param x
|
|
The x coordinate of the mouse.
|
|
@param y
|
|
The y coordinate of the mouse.
|
|
@param defResult
|
|
Suggested value for return value. Determined by SHIFT or CONTROL
|
|
key states.
|
|
|
|
@return The desired operation or wxDragNone. This is used for optical
|
|
feedback from the side of the drop source, typically in form
|
|
of changing the icon.
|
|
*/
|
|
virtual wxDragResult OnDragOver(wxCoord x, wxCoord y, wxDragResult defResult);
|
|
|
|
/**
|
|
Called when the user drops a data object on the target. Return @false
|
|
to veto the operation.
|
|
|
|
@param x
|
|
The x coordinate of the mouse.
|
|
@param y
|
|
The y coordinate of the mouse.
|
|
|
|
@return @true to accept the data, or @false to veto the operation.
|
|
*/
|
|
virtual bool OnDrop(wxCoord x, wxCoord y);
|
|
|
|
/**
|
|
Called when the mouse enters the drop target. By default, this calls
|
|
OnDragOver().
|
|
|
|
@param x
|
|
The x coordinate of the mouse.
|
|
@param y
|
|
The y coordinate of the mouse.
|
|
@param defResult
|
|
Suggested default for return value. Determined by SHIFT or CONTROL
|
|
key states.
|
|
|
|
@return The desired operation or wxDragNone. This is used for optical
|
|
feedback from the side of the drop source, typically in form
|
|
of changing the icon.
|
|
*/
|
|
virtual wxDragResult OnEnter(wxCoord x, wxCoord y, wxDragResult defResult);
|
|
|
|
/**
|
|
Called when the mouse leaves the drop target.
|
|
*/
|
|
virtual void OnLeave();
|
|
|
|
/**
|
|
Returns the data wxDataObject associated with the drop target
|
|
*/
|
|
wxDataObject *GetDataObject() const;
|
|
|
|
/**
|
|
Sets the data wxDataObject associated with the drop target and deletes
|
|
any previously associated data object.
|
|
*/
|
|
void SetDataObject(wxDataObject* data);
|
|
|
|
|
|
/**
|
|
Sets the default action for drag and drop. Use wxDragMove or
|
|
wxDragCopy to set default action to move or copy and use wxDragNone
|
|
(default) to set default action specified by initialization of dragging
|
|
(see wxDropSource::DoDragDrop())
|
|
*/
|
|
void SetDefaultAction(wxDragResult action);
|
|
|
|
/**
|
|
Returns default action for drag and drop or wxDragNone if this not
|
|
specified.
|
|
*/
|
|
wxDragResult GetDefaultAction();
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxDropSource
|
|
|
|
This class represents a source for a drag and drop operation.
|
|
|
|
@library{wxcore}
|
|
@category{dnd}
|
|
|
|
@see @ref overview_dnd, @ref overview_dataobject, wxDropTarget,
|
|
wxTextDropTarget, wxFileDropTarget
|
|
*/
|
|
class wxDropSource
|
|
{
|
|
public:
|
|
/**
|
|
This constructor requires that you must call SetData() later.
|
|
|
|
Note that the type of @a iconCopy and subsequent parameters
|
|
differs between different ports: these are cursors under Windows and OS
|
|
X but icons for GTK. You should use the macro wxDROP_ICON() in portable
|
|
programs instead of directly using either of these types.
|
|
|
|
@onlyfor{wxmsw,wxosx}
|
|
|
|
@param win
|
|
The window which initiates the drag and drop operation.
|
|
@param iconCopy
|
|
The icon or cursor used for feedback for copy operation.
|
|
@param iconMove
|
|
The icon or cursor used for feedback for move operation.
|
|
@param iconNone
|
|
The icon or cursor used for feedback when operation can't be done.
|
|
*/
|
|
wxDropSource(wxWindow* win = NULL,
|
|
const wxCursor& iconCopy = wxNullCursor,
|
|
const wxCursor& iconMove = wxNullCursor,
|
|
const wxCursor& iconNone = wxNullCursor);
|
|
|
|
/**
|
|
The constructor taking a wxDataObject.
|
|
|
|
Note that the type of @a iconCopy and subsequent parameters
|
|
differs between different ports: these are cursors under Windows and OS
|
|
X but icons for GTK. You should use the macro wxDROP_ICON() in portable
|
|
programs instead of directly using either of these types.
|
|
|
|
@onlyfor{wxmsw,wxosx}
|
|
|
|
@param data
|
|
The data associated with the drop source.
|
|
@param win
|
|
The window which initiates the drag and drop operation.
|
|
@param iconCopy
|
|
The icon or cursor used for feedback for copy operation.
|
|
@param iconMove
|
|
The icon or cursor used for feedback for move operation.
|
|
@param iconNone
|
|
The icon or cursor used for feedback when operation can't be done.
|
|
*/
|
|
wxDropSource(wxDataObject& data, wxWindow* win = NULL,
|
|
const wxCursor& iconCopy = wxNullCursor,
|
|
const wxCursor& iconMove = wxNullCursor,
|
|
const wxCursor& iconNone = wxNullCursor);
|
|
|
|
/**
|
|
This constructor requires that you must call SetData() later.
|
|
|
|
This is the wxGTK-specific version of the constructor taking wxIcon
|
|
instead of wxCursor as the other ports.
|
|
|
|
@onlyfor{wxgtk}
|
|
|
|
@param win
|
|
The window which initiates the drag and drop operation.
|
|
@param iconCopy
|
|
The icon or cursor used for feedback for copy operation.
|
|
@param iconMove
|
|
The icon or cursor used for feedback for move operation.
|
|
@param iconNone
|
|
The icon or cursor used for feedback when operation can't be done.
|
|
*/
|
|
wxDropSource(wxWindow* win = NULL,
|
|
const wxIcon& iconCopy = wxNullIcon,
|
|
const wxIcon& iconMove = wxNullIcon,
|
|
const wxIcon& iconNone = wxNullIcon);
|
|
|
|
/**
|
|
The constructor taking a wxDataObject.
|
|
|
|
This is the wxGTK-specific version of the constructor taking wxIcon
|
|
instead of wxCursor as the other ports.
|
|
|
|
@onlyfor{wxgtk}
|
|
|
|
@param data
|
|
The data associated with the drop source.
|
|
@param win
|
|
The window which initiates the drag and drop operation.
|
|
@param iconCopy
|
|
The icon or cursor used for feedback for copy operation.
|
|
@param iconMove
|
|
The icon or cursor used for feedback for move operation.
|
|
@param iconNone
|
|
The icon or cursor used for feedback when operation can't be done.
|
|
*/
|
|
wxDropSource(wxDataObject& data, wxWindow* win = NULL,
|
|
const wxIcon& iconCopy = wxNullIcon,
|
|
const wxIcon& iconMove = wxNullIcon,
|
|
const wxIcon& iconNone = wxNullIcon);
|
|
|
|
/**
|
|
Starts the drag-and-drop operation which will terminate when the user
|
|
releases the mouse. Call this in response to a mouse button press, for
|
|
example.
|
|
|
|
@param flags
|
|
If ::wxDrag_AllowMove is included in the flags, data may be moved
|
|
and not only copied as is the case for the default
|
|
::wxDrag_CopyOnly. If ::wxDrag_DefaultMove is specified
|
|
(which includes the previous flag), moving is not only possible but
|
|
becomes the default operation.
|
|
|
|
@return The operation requested by the user, may be ::wxDragCopy,
|
|
::wxDragMove, ::wxDragLink, ::wxDragCancel or ::wxDragNone if
|
|
an error occurred.
|
|
*/
|
|
virtual wxDragResult DoDragDrop(int flags = wxDrag_CopyOnly);
|
|
|
|
/**
|
|
Returns the wxDataObject object that has been assigned previously.
|
|
*/
|
|
wxDataObject* GetDataObject();
|
|
|
|
/**
|
|
You may give some custom UI feedback during the drag and drop operation
|
|
by overriding this function. It is called on each mouse move, so your
|
|
implementation must not be too slow.
|
|
|
|
@param effect
|
|
The effect to implement. One of ::wxDragCopy, ::wxDragMove,
|
|
::wxDragLink and ::wxDragNone.
|
|
|
|
@return @false if you want default feedback, or @true if you implement
|
|
your own feedback. The return value is ignored under GTK.
|
|
*/
|
|
virtual bool GiveFeedback(wxDragResult effect);
|
|
|
|
/**
|
|
Set the icon to use for a certain drag result.
|
|
|
|
@param res
|
|
The drag result to set the icon for.
|
|
@param cursor
|
|
The icon to show when this drag result occurs.
|
|
|
|
@onlyfor{wxmsw,wxosx}
|
|
*/
|
|
void SetCursor(wxDragResult res, const wxCursor& cursor);
|
|
|
|
/**
|
|
Set the icon to use for a certain drag result.
|
|
|
|
@param res
|
|
The drag result to set the icon for.
|
|
@param icon
|
|
The icon to show when this drag result occurs.
|
|
|
|
@onlyfor{wxgtk}
|
|
*/
|
|
void SetIcon(wxDragResult res, const wxIcon& icon);
|
|
|
|
/**
|
|
Sets the data wxDataObject associated with the drop source. This will
|
|
not delete any previously associated data.
|
|
*/
|
|
void SetData(wxDataObject& data);
|
|
};
|
|
|
|
|
|
|
|
/**
|
|
@class wxTextDropTarget
|
|
|
|
A predefined drop target for dealing with text data.
|
|
|
|
@library{wxcore}
|
|
@category{dnd}
|
|
|
|
@see @ref overview_dnd, wxDropSource, wxDropTarget, wxFileDropTarget
|
|
*/
|
|
class wxTextDropTarget : public wxDropTarget
|
|
{
|
|
public:
|
|
/**
|
|
Constructor.
|
|
*/
|
|
wxTextDropTarget();
|
|
|
|
/**
|
|
See wxDropTarget::OnDrop(). This function is implemented appropriately
|
|
for text, and calls OnDropText().
|
|
*/
|
|
virtual bool OnDrop(wxCoord x, wxCoord y);
|
|
|
|
/**
|
|
Override this function to receive dropped text.
|
|
|
|
@param x
|
|
The x coordinate of the mouse.
|
|
@param y
|
|
The y coordinate of the mouse.
|
|
@param data
|
|
The data being dropped: a wxString.
|
|
|
|
Return @true to accept the data, or @false to veto the operation.
|
|
*/
|
|
virtual bool OnDropText(wxCoord x, wxCoord y, const wxString& data) = 0;
|
|
};
|
|
|
|
|
|
/**
|
|
@class wxFileDropTarget
|
|
|
|
This is a drop target which accepts files (dragged from File Manager or
|
|
Explorer).
|
|
|
|
@library{wxcore}
|
|
@category{dnd}
|
|
|
|
@see @ref overview_dnd, wxDropSource, wxDropTarget, wxTextDropTarget
|
|
*/
|
|
class wxFileDropTarget : public wxDropTarget
|
|
{
|
|
public:
|
|
/**
|
|
Constructor.
|
|
*/
|
|
wxFileDropTarget();
|
|
|
|
/**
|
|
See wxDropTarget::OnDrop(). This function is implemented appropriately
|
|
for files, and calls OnDropFiles().
|
|
*/
|
|
virtual bool OnDrop(wxCoord x, wxCoord y);
|
|
|
|
/**
|
|
Override this function to receive dropped files.
|
|
|
|
@param x
|
|
The x coordinate of the mouse.
|
|
@param y
|
|
The y coordinate of the mouse.
|
|
@param filenames
|
|
An array of filenames.
|
|
|
|
Return @true to accept the data, or @false to veto the operation.
|
|
*/
|
|
virtual bool OnDropFiles(wxCoord x, wxCoord y,
|
|
const wxArrayString& filenames) = 0;
|
|
};
|
|
|
|
|
|
|
|
// ============================================================================
|
|
// Global functions/macros
|
|
// ============================================================================
|
|
|
|
/** @addtogroup group_funcmacro_gdi */
|
|
///@{
|
|
|
|
/**
|
|
This macro creates either a cursor (MSW) or an icon (elsewhere) with the
|
|
given @a name (of type <tt>const char*</tt>). Under MSW, the cursor is
|
|
loaded from the resource file and the icon is loaded from XPM file under
|
|
other platforms.
|
|
|
|
This macro should be used with wxDropSource::wxDropSource().
|
|
|
|
@return wxCursor on MSW, otherwise returns a wxIcon
|
|
|
|
@header{wx/dnd.h}
|
|
*/
|
|
#define wxDROP_ICON(name)
|
|
|
|
/**
|
|
Returns true if res indicates that something was done during a DnD operation,
|
|
i.e. is neither error nor none nor cancel.
|
|
*/
|
|
bool wxIsDragResultOk(wxDragResult res);
|
|
|
|
///@}
|
|
|