\section{\class{wxBitmapDataObject}}\label{wxbitmapdataobject}
- wxBitmapDataObject is a specialization of wxDataObject for bitmaps.
+wxBitmapDataObject is a specialization of wxDataObject for bitmap data. It can be
+used without change to paste data into the \helpref{wxClipboard}{wxclipboard}
+or a \helpref{wxDropSource}{wxdropsource}. A user may wish to derive a new class
+from this class for providing a bitmap on-demand in order to minimize memory consumption
+when offering data in several formats, such as a bitmap and GIF.
+
+In order to offer bitmap data on-demand \helpref{GetSize}{wxbitmapdataobjectgetsize}
+and \helpref{WriteData}{wxbitmapdataobjectwritedata} will have to be overridden.
\wxheading{Derived from}
\wxheading{See also}
-\helpref{wxDataObject}{wxdataobject}, \helpref{wxBitmap}{wxbitmap}
+\helpref{wxDataObject}{wxdataobject}
\latexignore{\rtfignore{\wxheading{Members}}}
\func{}{wxBitmapDataObject}{\void}
-Constructor. TODO: shouldn't there be a constructor taking a wxBitmap?
+Default constructor. Call \helpref{SetBitmap}{wxbitmapdataobjectsettext} later
+or override \helpref{WriteData}{wxbitmapdataobjectwritedata} and
+\helpref{GetSize}{wxbitmapdataobjectgetsize} for providing data on-demand.
-\membersection{wxBitmapDataObject::GetFormat}\label{wxbitmapdataobjectgetformat}
+\func{}{wxBitmapDataObject}{\param{const wxBitmap\& }{bitmap}}
-\func{virtual wxDataFormat}{GetFormat}{\void}
+Constructor, passing a bitmap.
-Returns wxDF\_BITMAP.
+\membersection{wxBitmapDataObject::GetSize}\label{wxbitmapdataobjectgetsize}
-\membersection{wxBitmapDataObject::SetBitmap}\label{wxbitmapdataobjectsetbitmap}
+\constfunc{virtual size\_t}{GetSize}{\void}
-\func{virtual void}{SetBitmap}{\param{const wxBitmap\& }{bitmap}}
+Returns the data size. By default, returns the size of the bitmap data
+set in the constructor or using \helpref{SetBitmap}{wxbitmapdataobjectsettext}.
+This can be overridden to provide size data on-demand. Note that you'd
+have to call the inherited GetSize method as this is the only way
+to get to know the transfer size of the bitmap in a platform dependent
+way - a bitmap has different size under GTK and Windows. In practice,
+this would look like this:
+
+\begin{verbatim}
+size_t MyBitmapDataObject::GetSize()
+{
+ // Get bitmap from global container. This container
+ // should be able to "produce" data in all formats
+ // offered by the application but store it only in
+ // one format to reduce memory consumption.
+
+ wxBitmap my_bitmap = my_global_container->GetBitmap();
+
+ // temporarily set bitmap
+
+ SetBitmap( my_bitmap );
-Sets the bitmap for the data object.
+ size_t ret = wxBitmapDataObject::GetSize();
+
+ // unset bitmap again
+
+ SetBitmap( wxNullBitmap );
-\membersection{wxBitmapDataObject::GetBitmap}\label{wxbitmapdataobjectgetbitmap}
+ retrun ret;
+}
+\end{verbatim}
+
+TODO: Offer a nicer way to do this. Maybe by providing a platform
+dependent function in this class like
+\begin{verbatim}
+size_t GetBitmapSize( const wxBitmap &bitmap )
+\end{verbatim}
+
+\membersection{wxBitmapDataObject::GetBitmap}\label{wxbitmapdataobjectgettext}
\constfunc{virtual wxBitmap}{GetBitmap}{\void}
-Returns the bitmap associated with the data object.
+Returns the bitmap associated with the data object. You may wish to override
+this method when offering data on-demand, but this is not required by
+wxWindows' internals. Use this method to get data in bitmap form from
+the \helpref{wxClipboard}{wxclipboard}.
+
+\membersection{wxBitmapDataObject::SetBitmap}\label{wxbitmapdataobjectsettext}
+
+\func{virtual void}{SetBitmap}{\param{const wxBitmap\& }{bitmap}}
+
+Sets the bitmap associated with the data object. This method is called
+internally when retrieving data from the \helpref{wxClipboard}{wxclipboard}
+and may be used to paste data to the clipboard directly (instead of
+on-demand).
+
+\membersection{wxBitmapDataObject::WriteData}\label{wxbitmapdataobjectwritedata}
+
+\constfunc{virtual void}{WriteData}{\param{void}{*dest} }
+
+Write the data owned by this class to {\it dest}. By default, this
+calls \helpref{WriteBitmap}{wxbitmapdataobjectwritebitmap} with the bitmap
+set in the constructor or using \helpref{SetBitmap}{wxbitmapdataobjectsetbitmap}.
+This can be overridden to provide bitmap data on-demand; in this case
+\helpref{WriteBitmap}{wxbitmapdataobjectwritebitmap} must be called from
+within th overriding WriteData() method.
+
+\membersection{wxBitmapDataObject::WriteBitmap}\label{wxbitmapdataobjectwritebitmap}
+
+\constfunc{void}{WriteBitmap}{\param{const wxBitmap\& }{bitmap}\param{void}{*dest} }
+
+Writes the the bitmap {\it bitmap} to {\it dest}. This method must be called
+from \helpref{WriteData}{wxbitmapdataobjectwritedata}.
\helpref{wxTextDropTarget}{wxtextdroptarget},
\helpref{wxFileDropTarget}{wxfiledroptarget}
-Samples: see the dnd sample.
-
-Headers: <wx/dataobj.h>, <wx/dropsrc.h and <wx/droptgt.h> or <wx/dnd.h>
-(note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h)
+It has to be noted that the API for drag and drop in wxWindows is not
+yet finnished which is mostly due to the fact that DnD support under
+GTK 1.0 is very rudimentary and entirely different from the XDnD
+protocoll used by GTK 1.2. This also entails that not all of the documentation
+concerning DnD might be correct and some of the code might get broken
+in the future. The next release of wxWindows will be based on GTK 1.2
+and will hopefully include a much improved DnD support. The general
+design on the wxDropSource side will be the same but especially the
+wxDropTarget is almost certain to change.
+
+Note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h in order
+to use Drag'n'Drop in wxWindows.
This overview describes wxWindows support for drag and drop and clipboard
operations. Both of these topics are discussed here because, in fact, they're
initialized with the data you wish to drag. For example:
\begin{verbatim}
- wxTextDataObject data("This string will be dragged.");
+ wxDataObject *my_data = new wxTextDataObject data("This string will be dragged.");
\end{verbatim}
-Of course, the data object may contain arbitrary data of any type, but for
-this you should derive your own class from \helpref{wxDataObject}{wxdataobject} overriding all of its pure virtual
-functions.
-
\item{\bf Drag start:} To start dragging process (typically in response to a
mouse click) you must call \helpref{DoDragDrop}{wxdropsourcedodragdrop} function
of wxDropSource object which should be constructed like this:
\begin{verbatim}
- wxDropSource dragSource(data, this);
-
- // or also:
-
- wxDropSource dragSource(this);
- dragSource.SetData(data);
+ wxDropSource dragSource( this );
+ dragSource.SetData( my_data );
\end{verbatim}
\item {\bf Dragging:} The call to DoDragDrop() blocks until the user release the
mouse button (unless you override \helpref{GiveFeedback}{wxdropsourcegivefeedback} function
to do something special). When the mouse moves in a window of a program which understands the
-same drag-and-drop protocol (any program under Windows or any program supporting XDnD protocol
-under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
+same drag-and-drop protocol (any program under Windows or any program supporting GTK 1.0
+DnD protocol under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
are called - see below.
\item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which
\section{\class{wxTextDataObject}}\label{wxtextdataobject}
- wxTextDataObject is a specialization of wxDataObject for text data.
+wxTextDataObject is a specialization of wxDataObject for text data. It can be
+used without change to paste data into the \helpref{wxClipboard}{wxclipboard}
+or a \helpref{wxDropSource}{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 offering data in several formats, such as plain text and RTF.
+
+In order to offer text data on-demand \helpref{GetSize}{wxtextdataobjectgetsize}
+and \helpref{WriteData}{wxtextdataobjectwritedata} will have to be overridden.
\wxheading{Derived from}
\func{}{wxTextDataObject}{\void}
-Default constructor.
+Default constructor. Call \helpref{SetText}{wxtextdataobjectsettext} later
+or override \helpref{WriteData}{wxtextdataobjectwritedata} and
+\helpref{GetSize}{wxtextdataobjectgetsize} for providing data on-demand.
\func{}{wxTextDataObject}{\param{const wxString\& }{strText}}
Constructor, passing text.
-\membersection{wxTextDataObject::GetFormat}\label{wxtextdataobjectgetformat}
+\membersection{wxTextDataObject::GetSize}\label{wxtextdataobjectgetsize}
+
+\constfunc{virtual size\_t}{GetSize}{\void}
+
+Returns the data size. By default, returns the size of the text data
+set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
+This can be overridden to provide text size data on-demand. It is recommended
+to return the text length plus 1 for a trailing zero, but this is not
+strictly required.
-\constfunc{virtual wxDataFormat}{GetFormat}{\void}
+\membersection{wxTextDataObject::GetText}\label{wxtextdataobjectgettext}
+
+\constfunc{virtual wxString}{GetText}{\void}
-Returns wxDF\_TEXT.
+Returns the text associated with the data object. You may wish to override
+this method when offering data on-demand, but this is not required by
+wxWindows' internals. Use this method to get data in text form from
+the \helpref{wxClipboard}{wxclipboard}.
\membersection{wxTextDataObject::SetText}\label{wxtextdataobjectsettext}
\func{virtual void}{SetText}{\param{const wxString\& }{strText}}
-Sets the text associated with the data object.
+Sets the text associated with the data object. This method is called
+internally when retrieving data from the \helpref{wxClipboard}{wxclipboard}
+and may be used to paste data to the clipboard directly (instead of
+on-demand).
-\membersection{wxTextDataObject::GetText}\label{wxtextdataobjectgettext}
+\membersection{wxTextDataObject::WriteData}\label{wxtextdataobjectwritedata}
-\constfunc{virtual wxString}{GetText}{\void}
+\constfunc{virtual void}{WriteData}{\param{void}{*dest} }
+
+Write the data owned by this class to {\it dest}. By default, this
+calls \helpref{WriteString}{wxtextobjectwritestring} with the string
+set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
+This can be overridden to provide text data on-demand; in this case
+\helpref{WriteString}{wxtextobjectwritestring} must be called from
+within the overriding WriteData() method.
+
+\membersection{wxTextDataObject::WriteString}\label{wxtextdataobjectwritestring}
+
+\constfunc{void}{WriteString}{\param{const wxString\& }{str}\param{void}{*dest} }
-Returns the text associated with the data object.
+Writes the the string {\it str} to {\it dest}. This method must be called
+from \helpref{WriteData}{wxtextdataobjectwritedata}.
Summary: The GTK+ 1.0 port of wxWindows library
Name: wxGTK
-Version: 2.0.1
+Version: 1.99.3
Release: 1
Copyright: wxWindows Licence
Group: X11/Libraries
projects / wxWidgets.git / commitdiff
