// Purpose: interface of wx*DataObject
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
@itemdef{wxDF_FILENAME,
A list of filenames.}
@itemdef{wxDF_HTML,
- An HTML string. This is only valid when passed to
- wxSetClipboardData when compiled with Visual C++ in non-Unicode
- mode.}
+ An HTML string. This is currently only valid on Mac and MSW.}
@endDefList
As mentioned above, these standard formats may be passed to any function
necessary initialisations and so an attempt to do clipboard format
registration at this time will usually lead to a crash!
- @library{wxbase}
+ @library{wxcore}
@category{dnd}
@see @ref overview_dnd, @ref page_samples_dnd, wxDataObject
/**
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);
*/
void SetType(wxDataFormatId type);
+ /**
+ Returns @true if the formats are different.
+ */
+ bool operator !=(const wxDataFormat& format) const;
+
/**
Returns @true if the formats are different.
*/
bool operator !=(wxDataFormatId format) const;
+ /**
+ Returns @true if the formats are equal.
+ */
+ bool operator ==(const wxDataFormat& format) const;
+
/**
Returns @true if the formats are equal.
*/
};
+const wxDataFormat wxFormatInvalid;
+
/**
@class wxDataObject
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
objects which only render their data or only set it (i.e. work in only one
direction), should return 0 from GetFormatCount().
- @beginWxPythonOnly
- At this time this class is not directly usable from wxPython. Derive a
- class from wxPyDataObjectSimple() instead.
- @endWxPythonOnly
-
@beginWxPerlOnly
This class is not currently usable from wxPerl; you may use
Wx::PlDataObjectSimple instead.
{
/** 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;
/**
- The method will write the data of the format @a format in the buffer
- @a buf and return @true on success, @false on failure.
+ The method will write the data of the format @a format to the buffer
+ @a buf. In other words, copy the data from this object in the given
+ format to the supplied buffer. Returns @true on success, @false on
+ failure.
*/
virtual bool GetDataHere(const wxDataFormat& format, void* buf) 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.
+ the buffer @a buf. In other words, copy length bytes of data from the
+ buffer to this data object.
+
+ @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);
/**
Set the data. The data object will make an internal copy.
-
- @beginWxPythonOnly
- This method expects a string in wxPython. You can pass nearly any
- object by pickling it first.
- @endWxPythonOnly
*/
virtual bool SetData(size_t size, const void* data);
/**
Like SetData(), but doesn't copy the data - instead the object takes
ownership of the pointer.
-
- @beginWxPythonOnly
- This method expects a string in wxPython. You can pass nearly any
- object by pickling it first.
- @endWxPythonOnly
*/
void TakeData(size_t size, void* data);
};
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,
+ wxDataObject::Direction dir = wxDataObject::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
be set must override SetData(). Of course, the objects supporting both
operations must override all three methods.
- @beginWxPythonOnly
- If you wish to create a derived wxDataObjectSimple class in wxPython you
- should derive the class from wxPyDataObjectSimple in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@beginWxPerlOnly
In wxPerl, you need to derive your data object class from
Wx::PlDataObjectSimple.
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
- When implementing this method in wxPython, no additional parameters are
- required and the data should be returned from the method as a string.
- @endWxPythonOnly
*/
virtual bool GetDataHere(void* buf) const;
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
- When implementing this method in wxPython, the data comes as a single
- string parameter rather than the two shown here.
- @endWxPythonOnly
*/
virtual bool SetData(size_t len, const void* buf);
This class may be used as is, but GetBitmap() may be overridden to increase
efficiency.
- @beginWxPythonOnly
- If you wish to create a derived wxBitmapDataObject class in wxPython you
- should derive the class from wxPyBitmapDataObject in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@library{wxcore}
@category{dnd}
/**
@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
wxStrings is already a very efficient operation (data is not actually
copied because wxStrings are reference counted).
- @beginWxPythonOnly
- If you wish to create a derived wxTextDataObject class in wxPython you
- should derive the class from wxPyTextDataObject in order to get
- Python-aware capabilities for the various virtual methods.
- @endWxPythonOnly
-
@library{wxcore}
@category{dnd}
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).
*/
- virtual size_t GetFormatCount(Direction dir = Get);
+ virtual size_t GetFormatCount(wxDataObject::Direction dir = wxDataObject::Get) const;
/**
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,
- Direction dir = Get) const = 0;
+ wxDataObject::Direction dir = wxDataObject::Get) const;
/**
Sets the text associated with the data object. This method is called
const wxArrayString& GetFilenames() const;
};
+/**
+ @class wxHTMLDataObject
+ wxHTMLDataObject is used for working with HTML-formatted text.
+
+ @library{wxcore}
+ @category{dnd}
+
+ @see wxDataObject, wxDataObjectSimple
+*/
+class wxHTMLDataObject : public wxDataObjectSimple
+{
+public:
+ /**
+ Constructor.
+ */
+ wxHTMLDataObject(const wxString& html = wxEmptyString);
+
+ /**
+ Returns the HTML string.
+ */
+ virtual wxString GetHTML() const;
+
+ /**
+ Sets the HTML string.
+ */
+ virtual void SetHTML(const wxString& html);
+};
projects / wxWidgets.git / blobdiff