// Purpose: interface of wx*DataObject
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
Constructs a data format object for one of the standard data formats or
an empty data object (use SetType() or SetId() later in this case).
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newNative(format).
+ @endWxPerlOnly
*/
wxDataFormat(wxDataFormatId format = wxDF_INVALID);
/**
Constructs a data format object for a custom format identified by its
name @a format.
+
+ @beginWxPerlOnly
+ In wxPerl use Wx::Bitmap->newUser(format).
+ @endWxPerlOnly
*/
wxDataFormat(const wxString& format);
set. In the general case, an object may support different formats on
'input' and 'output', i.e. it may be able to render itself in a given
format but not be created from data on this format or vice versa.
- wxDataObject defines the wxDataObject::Direction enumeration type which
+ wxDataObject defines the wxDataObject::Direction enumeration type which
distinguishes between them.
See wxDataFormat documentation for more about formats.
-# Use one of the built-in classes.
- You may use wxTextDataObject, wxBitmapDataObject wxFileDataObject,
- wxURLDataObject in the simplest cases when you only need to support
+ wxURLDataObject in the simplest cases when you only need to support
one format and your data is either text, bitmap or list of files.
-# Use wxDataObjectSimple
- Deriving from wxDataObjectSimple is the simplest solution for custom
{
/** Format is supported by GetDataHere() */
Get = 0x01,
-
+
/** Format is supported by SetData() */
Set = 0x02,
-
- /**
- Format is supported by both GetDataHere() and SetData()
- (unused currently)
+
+ /**
+ Format is supported by both GetDataHere() and SetData()
+ (unused currently)
*/
Both = 0x03
};
virtual ~wxDataObject();
/**
- Copies all formats supported in the given direction @a dir to the array
- pointed to by @a formats.
+ Copies all formats supported in the given direction @a dir to the array
+ pointed to by @a formats.
There must be enough space for GetFormatCount(dir) formats in it.
+
+ @beginWxPerlOnly
+ In wxPerl this method only takes the @a dir parameter. In scalar
+ context it returns the first format in the list, in list
+ context it returns a list containing all the supported
+ formats.
+ @endWxPerlOnly
*/
virtual void GetAllFormats(wxDataFormat* formats,
Direction dir = Get) const = 0;
Set the data in the format @a format of the length @a len provided in
the buffer @a buf.
- @return @true on success, @false on failure.
+ @param format
+ The format for which to set the data.
+ @param len
+ The size of data in bytes.
+ @param buf
+ Non-@NULL pointer to the data.
+ @return
+ @true on success, @false on failure.
*/
virtual bool SetData(const wxDataFormat& format, size_t len, const void* buf);
wxDataObject directly instead of wxDataObjectComposite for efficiency
reasons.
+ This example shows how a composite data object capable of storing either
+ bitmaps or file names (presumably of bitmap files) can be initialized and
+ used:
+
+ @code
+ MyDropTarget::MyDropTarget()
+ {
+ wxDataObjectComposite* dataobj = new wxDataObjectComposite();
+ dataobj->Add(new wxBitmapDataObject(), true);
+ dataobj->Add(new wxFileDataObject());
+ SetDataObject(dataobj);
+ }
+
+ wxDragResult MyDropTarget::OnData(wxCoord x, wxCoord y,
+ wxDragResult defaultDragResult)
+ {
+ wxDragResult dragResult = wxDropTarget::OnData(x, y, defaultDragResult);
+ if ( dragResult == defaultDragResult )
+ {
+ wxDataObjectComposite *
+ dataobjComp = static_cast<wxDataObjectComposite *>(GetDataObject());
+
+ wxDataFormat format = dataObjects->GetReceivedFormat();
+ wxDataObject *dataobj = dataobjComp->GetObject(format);
+ switch ( format.GetType() )
+ {
+ case wxDF_BITMAP:
+ {
+ wxBitmapDataObject *
+ dataobjBitmap = static_cast<wxBitmapDataObject *>(dataobj);
+
+ ... use dataobj->GetBitmap() ...
+ }
+ break;
+
+ case wxDF_FILENAME:
+ {
+ wxFileDataObject *
+ dataobjFile = static_cast<wxFileDataObject *>(dataobj);
+
+ ... use dataobj->GetFilenames() ...
+ }
+ break;
+
+ default:
+ wxFAIL_MSG( "unexpected data object format" );
+ }
+ }
+
+ return dragResult;
+ }
+ @endcode
+
@library{wxcore}
@category{dnd}
/**
Report the format passed to the SetData() method. This should be the
- format of the data object within the composite that recieved data from
+ format of the data object within the composite that received data from
the clipboard or the DnD operation. You can use this method to find
- out what kind of data object was recieved.
+ out what kind of data object was received.
*/
wxDataFormat GetReceivedFormat() const;
+
+ /**
+ Returns the pointer to the object which supports the passed format for
+ the specified direction.
+
+ @NULL is returned if the specified @a format is not supported for this
+ direction @a dir. The returned pointer is owned by wxDataObjectComposite
+ itself and shouldn't be deleted by caller.
+
+ @since 2.9.1
+ */
+ wxDataObjectSimple *GetObject(const wxDataFormat& format,
+ wxDataObjectBase::Direction dir = Get) const;
};
/**
@class wxDataObjectSimple
- This is the simplest possible implementation of the wxDataObject class.
- The data object of (a class derived from) this class only supports
- <strong>one format</strong>, so the number of virtual functions to
+ This is the simplest possible implementation of the wxDataObject class.
+ The data object of (a class derived from) this class only supports
+ <strong>one format</strong>, so the number of virtual functions to
be implemented is reduced.
Notice that this is still an abstract base class and cannot be used
wxDataObjectSimple(const wxDataFormat& format = wxFormatInvalid);
/**
- Copy the data to the buffer, return @true on success.
- Must be implemented in the derived class if the object supports rendering
+ Copy the data to the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports rendering
its data.
@beginWxPythonOnly
virtual size_t GetDataSize() const;
/**
- Returns the (one and only one) format supported by this object.
+ Returns the (one and only one) format supported by this object.
It is assumed that the format is supported in both directions.
*/
const wxDataFormat& GetFormat() const;
/**
- Copy the data from the buffer, return @true on success.
- Must be implemented in the derived class if the object supports setting
+ Copy the data from the buffer, return @true on success.
+ Must be implemented in the derived class if the object supports setting
its data.
@beginWxPythonOnly
/**
@class wxTextDataObject
- wxTextDataObject is a specialization of wxDataObjectSimple for text data.
+ wxTextDataObject is a specialization of wxDataObjectSimple for text data.
It can be used without change to paste data into the wxClipboard or a
wxDropSource. A user may wish to derive a new class from this class for
providing text on-demand in order to minimize memory consumption when
length plus 1 for a trailing zero, but this is not strictly required.
*/
virtual size_t GetTextLength() const;
-
+
/**
Returns 2 under wxMac and wxGTK, where text data coming from the
clipboard may be provided as ANSI (@c wxDF_TEXT) or as Unicode text
(@c wxDF_UNICODETEXT, but only when @c wxUSE_UNICODE==1).
-
+
Returns 1 under other platforms (e.g. wxMSW) or when building in ANSI mode
(@c wxUSE_UNICODE==0).
*/
/**
Returns the preferred format supported by this object.
-
+
This is @c wxDF_TEXT or @c wxDF_UNICODETEXT depending on the platform
and from the build mode (i.e. from @c wxUSE_UNICODE).
*/
/**
Returns all the formats supported by wxTextDataObject.
-
- Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
+
+ Under wxMac and wxGTK they are @c wxDF_TEXT and @c wxDF_UNICODETEXT,
under other ports returns only one of the two, depending on the build mode.
*/
virtual void GetAllFormats(wxDataFormat* formats,
projects / wxWidgets.git / blobdiff