docs for wxTextDataObjet and wxBitmapDataObject

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1525 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/bmpdatob.tex

@@ -1,6 +1,13 @@
 \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}
 
@@ -8,7 +15,7 @@
 
 \wxheading{See also}
 
-\helpref{wxDataObject}{wxdataobject}, \helpref{wxBitmap}{wxbitmap}
+\helpref{wxDataObject}{wxdataobject}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
@@ -16,23 +23,89 @@
 
 \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:
 
-Sets the bitmap for the data object.
+\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::GetBitmap}\label{wxbitmapdataobjectgetbitmap}
+  wxBitmap my_bitmap = my_global_container->GetBitmap();
+  
+  // temporarily set bitmap
+  
+  SetBitmap( my_bitmap );
+
+  size_t ret = wxBitmapDataObject::GetSize();
+  
+  // unset bitmap again
+  
+  SetBitmap( wxNullBitmap );
+
+  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}.
 

docs/latex/wx/tdnd.tex

@@ -7,10 +7,18 @@ Classes: \helpref{wxDataObject}{wxdataobject},
 \helpref{wxTextDropTarget}{wxtextdroptarget}, 
 \helpref{wxFileDropTarget}{wxfiledroptarget}
 
-Samples: see the dnd sample.
+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.
 
-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 in order
-(note that wxUSE\_DRAG\_AND\_DROP must be defined in setup.h)
+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
@@ -34,31 +42,23 @@ user elsewhere, you should implement the following steps:
 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);
+	wxDropSource dragSource( this );
-
+	dragSource.SetData( my_data );
-	// or also:
-
-	wxDropSource dragSource(this);
-	dragSource.SetData(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
+same drag-and-drop protocol (any program under Windows or any program supporting GTK 1.0
-under X Windows), the corresponding \helpref{wxDropTarget}{wxdroptarget} methods
+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

docs/latex/wx/txtdatob.tex

@@ -1,6 +1,13 @@
 \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}
 
@@ -16,27 +23,57 @@
 
 \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 wxDataFormat}{GetFormat}{\void}
+\constfunc{virtual size\_t}{GetSize}{\void}
 
-Returns wxDF\_TEXT.
+Returns the data size. By default, returns the size of the text data
-
+set in the constructor or using \helpref{SetText}{wxtextdataobjectsettext}.
-\membersection{wxTextDataObject::SetText}\label{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
-\func{virtual void}{SetText}{\param{const wxString\& }{strText}}
+strictly required.
-
-Sets the text associated with the data object.
 
 \membersection{wxTextDataObject::GetText}\label{wxtextdataobjectgettext}
 
 \constfunc{virtual wxString}{GetText}{\void}
 
-Returns the text associated with the data object.
+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. 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::WriteData}\label{wxtextdataobjectwritedata}
+
+\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} }
+
+Writes the the string {\it str} to {\it dest}. This method must be called
+from \helpref{WriteData}{wxtextdataobjectwritedata}.
 

wxGTK.spec

@@ -1,6 +1,6 @@
 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