X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a660d684eda27638bca0384b2058911a31c8e845..aaa6f9ba6bd0be1fe6a34800e6f753ffdc49900c:/docs/latex/wx/clipbrd.tex diff --git a/docs/latex/wx/clipbrd.tex b/docs/latex/wx/clipbrd.tex index a12f8b1f05..a216479e01 100644 --- a/docs/latex/wx/clipbrd.tex +++ b/docs/latex/wx/clipbrd.tex @@ -1,103 +1,156 @@ \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{Include files} + + + \wxheading{See also} -\helpref{wxClipboardClient}{wxclipboardclient}, \helpref{wxInitClipboard}{wxinitclipboard}. +\helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDataObject}{wxdataobject} \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.