wxPython documentation updates

[wxWidgets.git] / docs / latex / wx / bmpdatob.tex

diff --git a/docs/latex/wx/bmpdatob.tex b/docs/latex/wx/bmpdatob.tex
index 8519138f17333bbee271c4004fc9dfb020c89783..634794c0e1044d8b3ea82d4f0ad199facfe5f3af 100644 (file)
--- a/docs/latex/wx/bmpdatob.tex
+++ b/docs/latex/wx/bmpdatob.tex
@@ -1,14 +1,25 @@
 \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}
 
 \helpref{wxDataObject}{wxdataobject}
 
+\wxheading{Include files}
+
+<wx/dataobj.h>
+
 \wxheading{See also}
 
-\helpref{wxDataObject}{wxdataobject}, \helpref{wxBitmap}{wxbitmap}
+\helpref{wxDataObject}{wxdataobject}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -16,23 +27,90 @@
 
 \func{}{wxBitmapDataObject}{\void}
 
-Constructor. TODO: shouldn't there be a constructor taking a wxBitmap?
+Default constructor. Call \helpref{SetBitmap}{wxbitmapdataobjectsetbitmap} later
+or override \helpref{WriteData}{wxbitmapdataobjectwritedata} and 
+\helpref{GetSize}{wxbitmapdataobjectgetsize} for providing data on-demand.
+
+\func{}{wxBitmapDataObject}{\param{const wxBitmap\& }{bitmap}}
+
+Constructor, passing a bitmap.
+
+\membersection{wxBitmapDataObject::GetSize}\label{wxbitmapdataobjectgetsize}
+
+\constfunc{virtual size\_t}{GetSize}{\void}
+
+Returns the data size. By default, returns the size of the bitmap data
+set in the constructor or using \helpref{SetBitmap}{wxbitmapdataobjectsetbitmap}.
+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.
 
-\membersection{wxBitmapDataObject::GetFormat}\label{wxbitmapdataobjectgetformat}
+  wxBitmap my_bitmap = my_global_container->GetBitmap();
+  
+  // temporarily set bitmap
+  
+  SetBitmap( my_bitmap );
 
-\func{virtual wxDataFormat}{GetFormat}{\void}
+  size_t ret = wxBitmapDataObject::GetSize();
+  
+  // unset bitmap again
+  
+  SetBitmap( wxNullBitmap );
 
-Returns wxDF\_BITMAP.
+  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. 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{wxbitmapdataobjectsetbitmap}
 
 \func{virtual void}{SetBitmap}{\param{const wxBitmap\& }{bitmap}}
 
-Sets the bitmap for the data object.
+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::GetBitmap}\label{wxbitmapdataobjectgetbitmap}
+\membersection{wxBitmapDataObject::WriteData}\label{wxbitmapdataobjectwritedata}
 
-\constfunc{virtual wxBitmap}{GetBitmap}{\void}
+\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} }
 
-Returns the bitmap associated with the data object.
+Writes the the bitmap {\it bitmap} to {\it dest}. This method must be called
+from \helpref{WriteData}{wxbitmapdataobjectwritedata}.