\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 wxWindows 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.
+
+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
+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 object is held by the clipboard, so do not delete it in the app.
+ wxTextDataObject* object = new wxTextDataObject("Some text");
+ wxTheClipboard->SetData(& object);
+ wxTheClipboard->Close();
+ }
+
+ // Read some text
+ if (wxTheClipboard->Open() && wxTheClipboard->IsSupportedFormat(wxDF_TEXT))
+ {
+ wxTextDataObject object;
+ wxTheClipboard->GetData(& object);
+ wxTheClipboard->Close();
+
+ wxMessageBox(object.GetText());
+ }
+\end{verbatim}
\wxheading{Derived from}
\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}
-
-\func{wxClipboardClient *}{GetClipboardClient}{\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.
-
-\membersection{wxClipboard::GetClipboardData}
-
-\func{char*}{GetClipboardData}{\param{const wxString\& }{format}, \param{long *}{length}, \param{long}{ time}}
-
-Get data from the clipboard.
+\membersection{wxClipboard::wxClipboard}
-\membersection{wxClipboard::GetClipboardString}
+\func{}{wxClipboard}{\void}
-\func{wxString}{GetClipboardString}{\param{long}{ time}}
+Constructor.
-Get the data from the clipboard in the format ``TEXT".
+\membersection{wxClipboard::\destruct{wxClipboard}}
-\membersection{wxClipboard::SetClipboardClient}
+\func{}{\destruct{wxClipboard}}{\void}
-\func{void}{SetClipboardClient}{\param{wxClipboardClient *}{client}, \param{long}{ time}}
+Destructor.
-Set the clipboard data owner.
+\membersection{wxClipboard::Clear}\label{wxclipboardclear}
-\membersection{wxClipboard::SetClipboardString}
+\func{void}{Clear}{\void}
-\func{void}{SetClipboardString}{\param{const wxString\& }{data}, \param{long}{ time}}
+Clears the global clipboard object and the system's clipboard if possible.
-Set the clipboard string; does not require a client.
+\membersection{wxClipboard::Close}\label{wxclipboardclose}
-\section{\class{wxClipboardClient}}\label{wxclipboardclient}
+\func{bool}{Close}{\void}
-Implemented under X and MS Windows, a clipboard client holds data
-belonging to the clipboard. For plain text, a client is not necessary.
+Call this function to close the clipboard, having opened it with \helpref{wxClipboard::Close}{wxclipboardclose}.
-wxClipboardClient is an abstract class for which the virtual functions
-BeingReplaced and GetData must be overridden.
+\membersection{wxClipboard::GetData}\label{wxclipboardgetdata}
-\wxheading{Derived from}
-
-\helpref{wxObject}{wxobject}
+\func{bool}{GetData}{\param{wxDataObject*}{ data}}
-\wxheading{See also}
-
-\helpref{wxClipboard}{wxclipboard}, \helpref{wxInitClipboard}{wxinitclipboard}.
+Call this function to fill {\it data} with data on the clipboard, if available in the required
+format.
-\latexignore{\rtfignore{\wxheading{Members}}}
+\membersection{wxClipboard::IsSupportedFormat}\label{wxclipboardissupportedformat}
-\membersection{wxClipboardClient::formats}
+\func{bool}{IsSupportedFormat}{\param{wxDataFormat}{ format}, \param{const wxString\&}{ id = ""}}
-\member{wxStringList}{formats}
+Returns TRUE if the given format is available on the clipboard.
-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.
+\wxheading{Parameters}
-\membersection{wxClipboardClient::BeingReplaced}
+\docparam{format}{The format. See \helpref{wxDataObject}{wxdataobject} for a list of formats.}
-\func{void}{BeingReplaced}{\void}
+\docparam{id}{ If {\it format} is wxDF\_PRIVATE, {\it id} is the identifier of the private data format.}
-This method is called when the client is losing the selection.
+\membersection{wxClipboard::Open}\label{wxclipboardopen}
-\membersection{wxClipboardClient::GetData}
+\func{bool}{Open}{\void}
-\func{char*}{GetData}{\param{const wxString\& }{format}, \param{long *}{size}}
+Call this function to open the clipboard before calling \helpref{wxClipboard::SetData}{wxclipboardsetdata}
+and \helpref{wxClipboard::GetData}{wxclipboardgetdata}.
-This method is called when someone wants the data this client is
-supplying to the clipboard.
+Call \helpref{wxClipboard::Close}{wxclipboardclose} when you have finished with the clipboard. You
+should keep the clipboard open for only a very short time.
-{\it format} is a string indicating the
-format of the data - one of the strings from the ``formats"
-list.
+\membersection{wxClipboard::SetData}\label{wxclipboardsetdata}
-{\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.
+\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.
projects / wxWidgets.git / blobdiff