docs for wxTextDataObjet and wxBitmapDataObject

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

diff --git a/docs/latex/wx/bmpdatob.tex b/docs/latex/wx/bmpdatob.tex
index 8519138f17333bbee271c4004fc9dfb020c89783..3c2c283193e67e0386cd9b45e3aac28dceae0a40 100644 (file)
--- a/docs/latex/wx/bmpdatob.tex
+++ b/docs/latex/wx/bmpdatob.tex
@@ -1,6 +1,13 @@
 \section{\class{wxBitmapDataObject}}\label{wxbitmapdataobject}
 
 \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{Derived from}
 


@@ -8,7 +15,7 @@
 
 \wxheading{See also}
 
 
 \wxheading{See also}
 

-\helpref{wxDataObject}{wxdataobject}, \helpref{wxBitmap}{wxbitmap}
+\helpref{wxDataObject}{wxdataobject}

 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 


@@ -16,23 +23,89 @@
 
 \func{}{wxBitmapDataObject}{\void}
 
 
 \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}
 
 
 \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}.

 
 

diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex
index 85346110cc0312ae773922cfb4722f0125520a34..28c95e0be7cde15f6f59bd0c6a986fd3cb7250c9 100644 (file)
--- a/docs/latex/wx/tdnd.tex
+++ b/docs/latex/wx/tdnd.tex
@@ -7,10 +7,18 @@ Classes: \helpref{wxDataObject}{wxdataobject},
 \helpref{wxTextDropTarget}{wxtextdroptarget}, 
 \helpref{wxFileDropTarget}{wxfiledroptarget}
 
 \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
 
 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}
 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}
 
 \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}
 \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
 \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
 are called - see below.
 
 \item {\bf Processing the result:} DoDragDrop() returns an {\it effect code} which

diff --git a/docs/latex/wx/txtdatob.tex b/docs/latex/wx/txtdatob.tex
index 937489fb3a2064e7fc30609a60174eefd7b4dc7e..22a4b5341db97051bc75889f9197e0169851478e 100644 (file)
--- a/docs/latex/wx/txtdatob.tex
+++ b/docs/latex/wx/txtdatob.tex
@@ -1,6 +1,13 @@
 \section{\class{wxTextDataObject}}\label{wxtextdataobject}
 
 \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}
 
 
 \wxheading{Derived from}
 


@@ -16,27 +23,57 @@
 
 \func{}{wxTextDataObject}{\void}
 
 
 \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.
 
 
 \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}}
 
 
 \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}.

 
 

diff --git a/wxGTK.spec b/wxGTK.spec
index 13009c2c46f703871c931c0b3174eefa9823a7ea..0c91a27c3e3b7c4f2a0ac97ea305d178cc2c4bd5 100644 (file)
--- a/wxGTK.spec
+++ b/wxGTK.spec
@@ -1,6 +1,6 @@
 Summary: The GTK+ 1.0 port of wxWindows library
 Name: wxGTK
 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
 Release: 1
 Copyright: wxWindows Licence
 Group: X11/Libraries