From: Robert Roebling Date: Sat, 30 Jan 1999 15:58:31 +0000 (+0000) Subject: docs for wxTextDataObjet and wxBitmapDataObject X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/ab272c0bf8d2ca2d2d691215fbc0e65a8782f73d 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 8519138f17..3c2c283193 100644 --- a/docs/latex/wx/bmpdatob.tex +++ b/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: + +\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}. diff --git a/docs/latex/wx/tdnd.tex b/docs/latex/wx/tdnd.tex index 85346110cc..28c95e0be7 100644 --- 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} -Samples: see the dnd sample. - -Headers: , or -(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 @@ -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); - - // 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 diff --git a/docs/latex/wx/txtdatob.tex b/docs/latex/wx/txtdatob.tex index 937489fb3a..22a4b5341d 100644 --- a/docs/latex/wx/txtdatob.tex +++ b/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 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}. diff --git a/wxGTK.spec b/wxGTK.spec index 13009c2c46..0c91a27c3e 100644 --- a/wxGTK.spec +++ b/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