docs/latex/wx/clipbrd.tex

   1 \section{\class{wxClipboard}}\label{wxclipboard}
   2
   3 A class for manipulating the clipboard. Note that this is not compatible with the
   4 clipboard class from wxWidgets 1.xx, which has the same name but a different implementation.
   5
   6 To use the clipboard, you call member functions of the global {\bf wxTheClipboard} object.
   7
   8 See also the \helpref{wxDataObject overview}{wxdataobjectoverview} for further information.
   9
  10 Call \helpref{wxClipboard::Open}{wxclipboardopen} to get ownership of the clipboard. If this operation returns true, you
  11 now own the clipboard. Call \helpref{wxClipboard::SetData}{wxclipboardsetdata} to put data
  12 on the clipboard, or \helpref{wxClipboard::GetData}{wxclipboardgetdata} to
  13 retrieve data from the clipboard. Call \helpref{wxClipboard::Close}{wxclipboardclose} to close
  14 the clipboard and relinquish ownership. You should keep the clipboard open only momentarily.
  15
  16 For example:
  17
  18 \begin{verbatim}
  19   // Write some text to the clipboard
  20   if (wxTheClipboard->Open())
  21   {
  22     // This data objects are held by the clipboard,
  23     // so do not delete them in the app.
  24     wxTheClipboard->SetData( new wxTextDataObject("Some text") );
  25     wxTheClipboard->Close();
  26   }
  27
  28   // Read some text
  29   if (wxTheClipboard->Open())
  30   {
  31     if (wxTheClipboard->IsSupported( wxDF_TEXT ))
  32     {
  33       wxTextDataObject data;
  34       wxTheClipboard->GetData( data );
  35       wxMessageBox( data.GetText() );
  36     }
  37     wxTheClipboard->Close();
  38   }
  39 \end{verbatim}
  40
  41 \wxheading{Derived from}
  42
  43 \helpref{wxObject}{wxobject}
  44
  45 \wxheading{Include files}
  46
  47 <wx/clipbrd.h>
  48
  49 \wxheading{See also}
  50
  51 \helpref{Drag and drop overview}{wxdndoverview}, \helpref{wxDataObject}{wxdataobject}
  52
  53 \latexignore{\rtfignore{\wxheading{Members}}}
  54
  55 \membersection{wxClipboard::wxClipboard}
  56
  57 \func{}{wxClipboard}{\void}
  58
  59 Constructor.
  60
  61 \membersection{wxClipboard::\destruct{wxClipboard}}
  62
  63 \func{}{\destruct{wxClipboard}}{\void}
  64
  65 Destructor.
  66
  67 \membersection{wxClipboard::AddData}\label{wxclipboardadddata}
  68
  69 \func{bool}{AddData}{\param{wxDataObject*}{ data}}
  70
  71 Call this function to add the data object to the clipboard. You may call
  72 this function repeatedly after having cleared the clipboard using \helpref{wxClipboard::Clear}{wxclipboardclear}.
  73
  74 After this function has been called, the clipboard owns the data, so do not delete
  75 the data explicitly.
  76
  77 \wxheading{See also}
  78
  79 \helpref{wxClipboard::SetData}{wxclipboardsetdata}
  80
  81 \membersection{wxClipboard::Clear}\label{wxclipboardclear}
  82
  83 \func{void}{Clear}{\void}
  84
  85 Clears the global clipboard object and the system's clipboard if possible.
  86
  87 \membersection{wxClipboard::Close}\label{wxclipboardclose}
  88
  89 \func{void}{Close}{\void}
  90
  91 Call this function to close the clipboard, having opened it with \helpref{wxClipboard::Open}{wxclipboardopen}.
  92
  93 \membersection{wxClipboard::Flush}\label{wxclipboardflush}
  94
  95 \func{bool}{Flush}{\void}
  96
  97 Flushes the clipboard: this means that the data which is currently on
  98 clipboard will stay available even after the application exits (possibly
  99 eating memory), otherwise the clipboard will be emptied on exit.
 100 Returns false if the operation is unsuccesful for any reason.
 101
 102 \membersection{wxClipboard::GetData}\label{wxclipboardgetdata}
 103
 104 \func{bool}{GetData}{\param{wxDataObject\&}{ data}}
 105
 106 Call this function to fill {\it data} with data on the clipboard, if available in the required
 107 format. Returns true on success.
 108
 109 \membersection{wxClipboard::IsOpened}\label{wxclipboardisopened}
 110
 111 \constfunc{bool}{IsOpened}{\void}
 112
 113 Returns true if the clipboard has been opened.
 114
 115 \membersection{wxClipboard::IsSupported}\label{wxclipboardissupported}
 116
 117 \func{bool}{IsSupported}{\param{const wxDataFormat\&}{ format}}
 118
 119 Returns true if the format of the given data object is available on the clipboard.
 120
 121 \membersection{wxClipboard::Open}\label{wxclipboardopen}
 122
 123 \func{bool}{Open}{\void}
 124
 125 Call this function to open the clipboard before calling \helpref{wxClipboard::SetData}{wxclipboardsetdata}
 126 and \helpref{wxClipboard::GetData}{wxclipboardgetdata}.
 127
 128 Call \helpref{wxClipboard::Close}{wxclipboardclose} when you have finished with the clipboard. You
 129 should keep the clipboard open for only a very short time.
 130
 131 Returns true on success. This should be tested (as in the sample shown above).
 132
 133 \membersection{wxClipboard::SetData}\label{wxclipboardsetdata}
 134
 135 \func{bool}{SetData}{\param{wxDataObject*}{ data}}
 136
 137 Call this function to set the data object to the clipboard. This function will
 138 clear all previous contents in the clipboard, so calling it several times
 139 does not make any sense.
 140
 141 After this function has been called, the clipboard owns the data, so do not delete
 142 the data explicitly.
 143
 144 \wxheading{See also}
 145
 146 \helpref{wxClipboard::AddData}{wxclipboardadddata}
 147
 148 \membersection{wxClipboard::UsePrimarySelection}\label{wxclipboarduseprimary}
 149
 150 \func{void}{UsePrimarySelection}{\param{bool}{ primary = true}}
 151
 152 On platforms supporting it (currently only GTK), selects the so called
 153 PRIMARY SELECTION as the clipboard as opposed to the normal clipboard,
 154 if {\it primary} is true.
 155
 156