Line-up interfaces to use size_t for GetCount()s (and count related api).

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

diff --git a/docs/latex/wx/clipbrd.tex b/docs/latex/wx/clipbrd.tex
index a12f8b1f057d4bdc470095da617ef9a3cac128f7..a216479e018081c9fc45bedf2bb07b0794c47b64 100644 (file)
--- a/docs/latex/wx/clipbrd.tex
+++ b/docs/latex/wx/clipbrd.tex
@@ -1,103 +1,156 @@
 \section{\class{wxClipboard}}\label{wxclipboard}
 
 \section{\class{wxClipboard}}\label{wxclipboard}
 

-There is one wxClipboard object referenced by the pointer
-wxTheClipboard, initialized by calling \helpref{wxInitClipboard}{wxinitclipboard}.
-Under X, clipboard manipulation must be done by using this class, and
-such code will work under MS Windows also. Under MS Windows, you have the
-alternative of using the normal clipboard functions.
-
-The documentation for this class will be expanded in due course. At present,
-wxClipboard is only used in the wxMediaWindow add-on library.
+A class for manipulating the clipboard. Note that this is not compatible with the
+clipboard class from wxWidgets 1.xx, which has the same name but a different implementation.
+
+To use the clipboard, you call member functions of the global {\bf wxTheClipboard} object.
+
+See also the \helpref{wxDataObject overview}{wxdataobjectoverview} for further information.
+
+Call \helpref{wxClipboard::Open}{wxclipboardopen} to get ownership of the clipboard. If this operation returns true, you
+now own the clipboard. Call \helpref{wxClipboard::SetData}{wxclipboardsetdata} to put data
+on the clipboard, or \helpref{wxClipboard::GetData}{wxclipboardgetdata} to
+retrieve data from the clipboard. Call \helpref{wxClipboard::Close}{wxclipboardclose} to close
+the clipboard and relinquish ownership. You should keep the clipboard open only momentarily.
+
+For example:
+
+\begin{verbatim}
+  // Write some text to the clipboard
+  if (wxTheClipboard->Open())
+  {
+    // This data objects are held by the clipboard, 
+    // so do not delete them in the app.
+    wxTheClipboard->SetData( new wxTextDataObject("Some text") );
+    wxTheClipboard->Close();
+  }
+
+  // Read some text
+  if (wxTheClipboard->Open())
+  {
+    if (wxTheClipboard->IsSupported( wxDF_TEXT ))
+    {
+      wxTextDataObject data;
+      wxTheClipboard->GetData( data );
+      wxMessageBox( data.GetText() );
+    }  
+    wxTheClipboard->Close();
+  }
+\end{verbatim}

 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 
 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/clipbrd.h>
+

 \wxheading{See also}
 
 \wxheading{See also}
 

-\helpref{wxClipboardClient}{wxclipboardclient}, \helpref{wxInitClipboard}{wxinitclipboard}.
+\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDataObject}{wxdataobject}

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

-\membersection{wxClipboard::GetClipboardClient}
+\membersection{wxClipboard::wxClipboard}\label{wxclipboardctor}

 
 

-\func{wxClipboardClient *}{GetClipboardClient}{\void}
+\func{}{wxClipboard}{\void}

 
 

-Get the clipboard client directly. Will be NULL if clipboard data
-is a string, or if some other application owns the clipboard. 
-This can be useful for shortcutting data translation, if the
-clipboard user can check for a specific client.
+Constructor.

 
 

-\membersection{wxClipboard::GetClipboardData}
+\membersection{wxClipboard::\destruct{wxClipboard}}\label{wxclipboarddtor}

 
 

-\func{char*}{GetClipboardData}{\param{const wxString\& }{format}, \param{long *}{length}, \param{long}{ time}}
+\func{}{\destruct{wxClipboard}}{\void}

 
 

-Get data from the clipboard.
+Destructor.

 
 

-\membersection{wxClipboard::GetClipboardString}
+\membersection{wxClipboard::AddData}\label{wxclipboardadddata}

 
 

-\func{wxString}{GetClipboardString}{\param{long}{ time}}
+\func{bool}{AddData}{\param{wxDataObject*}{ data}}

 
 

-Get the data from the clipboard in the format ``TEXT".
+Call this function to add the data object to the clipboard. You may call
+this function repeatedly after having cleared the clipboard using \helpref{wxClipboard::Clear}{wxclipboardclear}.

 
 

-\membersection{wxClipboard::SetClipboardClient}
+After this function has been called, the clipboard owns the data, so do not delete
+the data explicitly.

 
 

-\func{void}{SetClipboardClient}{\param{wxClipboardClient *}{client}, \param{long}{ time}}
+\wxheading{See also}

 
 

-Set the clipboard data owner.
+\helpref{wxClipboard::SetData}{wxclipboardsetdata}

 
 

-\membersection{wxClipboard::SetClipboardString}
+\membersection{wxClipboard::Clear}\label{wxclipboardclear}

 
 

-\func{void}{SetClipboardString}{\param{const wxString\& }{data}, \param{long}{ time}}
+\func{void}{Clear}{\void}

 
 

-Set the clipboard string; does not require a client.
+Clears the global clipboard object and the system's clipboard if possible.

 
 

-\section{\class{wxClipboardClient}}\label{wxclipboardclient}
+\membersection{wxClipboard::Close}\label{wxclipboardclose}

 
 

-Implemented under X and MS Windows, a clipboard client holds data
-belonging to the clipboard. For plain text, a client is not necessary.
+\func{void}{Close}{\void}

 
 

-wxClipboardClient is an abstract class for which the virtual functions
-BeingReplaced and GetData must be overridden.
+Call this function to close the clipboard, having opened it with \helpref{wxClipboard::Open}{wxclipboardopen}.

 
 

-\wxheading{Derived from}
+\membersection{wxClipboard::Flush}\label{wxclipboardflush}

 
 

-\helpref{wxObject}{wxobject}
+\func{bool}{Flush}{\void}

 
 

-\wxheading{See also}
+Flushes the clipboard: this means that the data which is currently on
+clipboard will stay available even after the application exits (possibly
+eating memory), otherwise the clipboard will be emptied on exit.
+Returns false if the operation is unsuccessful for any reason.

 
 

-\helpref{wxClipboard}{wxclipboard}, \helpref{wxInitClipboard}{wxinitclipboard}.
+\membersection{wxClipboard::GetData}\label{wxclipboardgetdata}

 
 

-\latexignore{\rtfignore{\wxheading{Members}}}
+\func{bool}{GetData}{\param{wxDataObject\&}{ data}}
+
+Call this function to fill {\it data} with data on the clipboard, if available in the required
+format. Returns true on success.
+
+\membersection{wxClipboard::IsOpened}\label{wxclipboardisopened}

 
 

-\membersection{wxClipboardClient::formats}
+\constfunc{bool}{IsOpened}{\void}

 
 

-\member{wxStringList}{formats}
+Returns true if the clipboard has been opened.

 
 

-This list should be filled in with strings indicating the formats
-this client can provide. Almost all clients will provide``TEXT".
-Format names should be 4 characters long, so things will work
-out on the Macintosh.
+\membersection{wxClipboard::IsSupported}\label{wxclipboardissupported}

 
 

-\membersection{wxClipboardClient::BeingReplaced}
+\func{bool}{IsSupported}{\param{const wxDataFormat\&}{ format}}

 
 

-\func{void}{BeingReplaced}{\void}
+Returns true if there is data which matches the data format of the given data object currently {\bf available} (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard.

 
 

-This method is called when the client is losing the selection.
+\membersection{wxClipboard::Open}\label{wxclipboardopen}

 
 

-\membersection{wxClipboardClient::GetData}
+\func{bool}{Open}{\void}
+
+Call this function to open the clipboard before calling \helpref{wxClipboard::SetData}{wxclipboardsetdata} 
+and \helpref{wxClipboard::GetData}{wxclipboardgetdata}.
+
+Call \helpref{wxClipboard::Close}{wxclipboardclose} when you have finished with the clipboard. You
+should keep the clipboard open for only a very short time.
+
+Returns true on success. This should be tested (as in the sample shown above).
+
+\membersection{wxClipboard::SetData}\label{wxclipboardsetdata}
+
+\func{bool}{SetData}{\param{wxDataObject*}{ data}}
+
+Call this function to set the data object to the clipboard. This function will
+clear all previous contents in the clipboard, so calling it several times
+does not make any sense.
+
+After this function has been called, the clipboard owns the data, so do not delete
+the data explicitly.
+
+\wxheading{See also}

 
 

-\func{char*}{GetData}{\param{const wxString\& }{format}, \param{long *}{size}}
+\helpref{wxClipboard::AddData}{wxclipboardadddata}

 
 

-This method is called when someone wants the data this client is
-supplying to the clipboard.
+\membersection{wxClipboard::UsePrimarySelection}\label{wxclipboarduseprimary}

 
 

-{\it format} is a string indicating the
-format of the data - one of the strings from the ``formats"
-list.
+\func{void}{UsePrimarySelection}{\param{bool}{ primary = true}}

 
 

-{\it size} should be filled with the size of the resulting
-data. In the case of text, {\it size} does not count the
-NULL terminator.
+On platforms supporting it (currently only GTK), selects the so called
+PRIMARY SELECTION as the clipboard as opposed to the normal clipboard,
+if {\it primary} is true.