X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/dface61ccba162c922b25d18aca2ebc4e6f03312..1e9693318372b3321c400fc7a1746bbcd696eceb:/docs/latex/wx/clipbrd.tex diff --git a/docs/latex/wx/clipbrd.tex b/docs/latex/wx/clipbrd.tex index c8cefc54b9..cba1926fb1 100644 --- 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 -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 -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} - wxClipboard 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 - 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} @@ -38,54 +42,99 @@ For example: \helpref{wxObject}{wxobject} +\wxheading{Include files} + + + \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. -\membersection{wxClipboard::\destruct{wxClipboard}} + +\membersection{wxClipboard::\destruct{wxClipboard}}\label{wxclipboarddtor} \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::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} -\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 -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} @@ -97,10 +146,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. +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 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.