fixed doc wrong position of \wxheading{Library}

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

diff --git a/docs/latex/wx/clipbrd.tex b/docs/latex/wx/clipbrd.tex
index c8cefc54b9af20a29fbb79c28d178fe688d4adff..4197118b286e2ed32c6f46a175cd8a91327e2f9c 100644 (file)
--- a/docs/latex/wx/clipbrd.tex
+++ b/docs/latex/wx/clipbrd.tex
@@ -1,36 +1,40 @@
 \section{\class{wxClipboard}}\label{wxclipboard}
 
 A class for manipulating the clipboard. Note that this is not compatible with the
 \section{\class{wxClipboard}}\label{wxclipboard}
 
 A class for manipulating the clipboard. Note that this is not compatible with the

-clipboard class from wxWindows 1.xx, which has the same name but a different implementation.
+clipboard class from wxWidgets 1.xx, which has the same name but a different implementation.

 
 

-To use the clipboard, construct a wxClipboard object on the stack and 
-call \helpref{wxClipboard::Open}{wxclipboardopen}. If this operation returns TRUE, you
+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
 now own the clipboard. Call \helpref{wxClipboard::SetData}{wxclipboardsetdata} to put data

-on the clipboard (one or more times), or \helpref{wxClipboard::GetData}{wxclipboardgetdata} to
+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}
 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}

-  wxClipboard clipboard;
-

   // Write some text to the clipboard
   // Write some text to the clipboard

-  if (clipboard.Open())
+  if (wxTheClipboard->Open())

   {
   {

-    wxTextDataObject object("Some text");
-    clipboard.SetData(& object);
-    clipboard.Close();
+    // 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
   }
 
   // Read some text

-  if (clipboard.Open() && clipboard.IsSupportedFormat(wxDF_TEXT))
+  if (wxTheClipboard->Open())

   {
   {

-    wxTextDataObject object;
-    clipboard.GetData(& object);
-    clipboard.Close();
-
-    wxMessageBox(object.GetText());
+    if (wxTheClipboard->IsSupported( wxDF_TEXT ))
+    {
+      wxTextDataObject data;
+      wxTheClipboard->GetData( data );
+      wxMessageBox( data.GetText() );
+    }  
+    wxTheClipboard->Close();

   }
 \end{verbatim}
 
   }
 \end{verbatim}
 


@@ -38,54 +42,103 @@ For example:
 
 \helpref{wxObject}{wxobject}
 
 
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/clipbrd.h>
+
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \wxheading{See also}
 
 \helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDataObject}{wxdataobject}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \wxheading{See also}
 
 \helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDataObject}{wxdataobject}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

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

 
 \func{}{wxClipboard}{\void}
 
 Constructor.
 
 
 \func{}{wxClipboard}{\void}
 
 Constructor.
 

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

 
 \func{}{\destruct{wxClipboard}}{\void}
 
 Destructor.
 
 
 \func{}{\destruct{wxClipboard}}{\void}
 
 Destructor.
 

+
+\membersection{wxClipboard::AddData}\label{wxclipboardadddata}
+
+\func{bool}{AddData}{\param{wxDataObject*}{ data}}
+
+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}.
+
+After this function has been called, the clipboard owns the data, so do not delete
+the data explicitly.
+
+\wxheading{See also}
+
+\helpref{wxClipboard::SetData}{wxclipboardsetdata}
+
+

 \membersection{wxClipboard::Clear}\label{wxclipboardclear}
 
 \func{void}{Clear}{\void}
 
 Clears the global clipboard object and the system's clipboard if possible.
 
 \membersection{wxClipboard::Clear}\label{wxclipboardclear}
 
 \func{void}{Clear}{\void}
 
 Clears the global clipboard object and the system's clipboard if possible.
 

+

 \membersection{wxClipboard::Close}\label{wxclipboardclose}
 
 \membersection{wxClipboard::Close}\label{wxclipboardclose}
 

-\func{bool}{Close}{\void}
+\func{void}{Close}{\void}
+
+Call this function to close the clipboard, having opened it with \helpref{wxClipboard::Open}{wxclipboardopen}.
+
+
+\membersection{wxClipboard::Flush}\label{wxclipboardflush}
+
+\func{bool}{Flush}{\void}
+
+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.

 
 

-Call this function to close the clipboard, having opened it with \helpref{wxClipboard::Close}{wxclipboardclose}.

 
 \membersection{wxClipboard::GetData}\label{wxclipboardgetdata}
 
 
 \membersection{wxClipboard::GetData}\label{wxclipboardgetdata}
 

-\func{bool}{GetData}{\param{wxDataObject*}{ data}}
+\func{bool}{GetData}{\param{wxDataObject\&}{ data}}

 
 Call this function to fill {\it data} with data on the clipboard, if available in the required
 
 Call this function to fill {\it data} with data on the clipboard, if available in the required

-format.
+format. Returns true on success.
+
+
+\membersection{wxClipboard::IsOpened}\label{wxclipboardisopened}
+
+\constfunc{bool}{IsOpened}{\void}

 
 

-\membersection{wxClipboard::IsSupportedFormat}\label{wxclipboardissupportedformat}
+Returns true if the clipboard has been opened.

 
 

-\func{bool}{IsSupportedFormat}{\param{wxDataFormat}{ format}, \param{const wxString\&}{ id = ""}}

 
 

-Returns TRUE if the given format is available on the clipboard.
+\membersection{wxClipboard::IsSupported}\label{wxclipboardissupported}

 
 

-\wxheading{Parameters}
+\func{bool}{IsSupported}{\param{const wxDataFormat\&}{ format}}

 
 

-\docparam{format}{The format. See \helpref{wxDataObject}{wxdataobject} for a list of formats.}
+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.
+
+
+\membersection{wxClipboard::IsUsingPrimarySelection}\label{wxclipboardisusingprimaryselection}
+
+\constfunc{bool}{IsUsingPrimarySelection}{\void}
+
+Returns \true if we are using the primary selection, \false if clipboard one.
+See \helpref{UsePrimarySelection}{wxclipboarduseprimary} for more information.

 
 

-\docparam{id}{ If {\it format} is wxDF\_PRIVATE, {\it id} is the identifier of the private data format.}

 
 \membersection{wxClipboard::Open}\label{wxclipboardopen}
 
 
 \membersection{wxClipboard::Open}\label{wxclipboardopen}
 


@@ -97,10 +150,39 @@ 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.
 
 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}}
 
 \membersection{wxClipboard::SetData}\label{wxclipboardsetdata}
 
 \func{bool}{SetData}{\param{wxDataObject*}{ data}}
 

-Call this function to set a data object to the clipboard. This function can be called several times
-to put different formats on the clipboard.
+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}
+
+\helpref{wxClipboard::AddData}{wxclipboardadddata}
+
+
+\membersection{wxClipboard::UsePrimarySelection}\label{wxclipboarduseprimary}
+
+\func{void}{UsePrimarySelection}{\param{bool}{ primary = true}}
+
+On platforms supporting it (all X11-based ports), wxClipboard uses the
+CLIPBOARD X11 selection by default. When this function is called with \true
+argument, all subsequent clipboard operations will use PRIMARY selection until
+this function is called again with \false.
+
+On the other platforms, there is no PRIMARY selection and so all clipboard
+operations will fail. This allows to implement the standard X11 handling of the
+clipboard which consists in copying data to the CLIPBOARD selection only when
+the user explicitly requests it (i.e. by selection \texttt{"Copy"} menu
+command) but putting the currently selected text into the PRIMARY selection
+automatically, without overwriting the normal clipboard contents with the
+currently selected text on the other platforms.