interface/clipbrd.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        clipbrd.h
   3 // Purpose:     interface of wxClipboard
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     The backwards compatible access macro that returns the global clipboard
  11     object pointer.
  12 */
  13 #define wxTheClipboard
  14
  15 /**
  16     @class wxClipboard
  17     @wxheader{clipbrd.h}
  18
  19     A class for manipulating the clipboard.
  20
  21     To use the clipboard, you call member functions of the global
  22     ::wxTheClipboard object.
  23
  24     See the @ref overview_dataobject for further information.
  25
  26     Call wxClipboard::Open() to get ownership of the clipboard. If this
  27     operation returns @true, you now own the clipboard. Call
  28     wxClipboard::SetData() to put data on the clipboard, or
  29     wxClipboard::GetData() to retrieve data from the clipboard. Call
  30     wxClipboard::Close() to close the clipboard and relinquish ownership. You
  31     should keep the clipboard open only momentarily.
  32
  33     For example:
  34
  35     @code
  36     // Write some text to the clipboard
  37     if (wxTheClipboard->Open())
  38     {
  39         // This data objects are held by the clipboard,
  40         // so do not delete them in the app.
  41         wxTheClipboard->SetData( new wxTextDataObject("Some text") );
  42         wxTheClipboard->Close();
  43     }
  44
  45     // Read some text
  46     if (wxTheClipboard->Open())
  47     {
  48         if (wxTheClipboard->IsSupported( wxDF_TEXT ))
  49         {
  50             wxTextDataObject data;
  51             wxTheClipboard->GetData( data );
  52             wxMessageBox( data.GetText() );
  53         }
  54         wxTheClipboard->Close();
  55     }
  56     @endcode
  57
  58     @library{wxcore}
  59     @category{dnd}
  60
  61     @see @ref overview_dnd, @ref overview_dataobject, wxDataObject
  62 */
  63 class wxClipboard : public wxObject
  64 {
  65 public:
  66     /**
  67         Default constructor.
  68     */
  69     wxClipboard();
  70
  71     /**
  72         Destructor.
  73     */
  74     ~wxClipboard();
  75
  76     /**
  77         Call this function to add the data object to the clipboard. You may
  78         call this function repeatedly after having cleared the clipboard using
  79         Clear().
  80
  81         After this function has been called, the clipboard owns the data, so do
  82         not delete the data explicitly.
  83
  84         @see SetData()
  85     */
  86     bool AddData(wxDataObject* data);
  87
  88     /**
  89         Clears the global clipboard object and the system's clipboard if
  90         possible.
  91     */
  92     void Clear();
  93
  94     /**
  95         Call this function to close the clipboard, having opened it with
  96         Open().
  97     */
  98     void Close();
  99
 100     /**
 101         Flushes the clipboard: this means that the data which is currently on
 102         clipboard will stay available even after the application exits
 103         (possibly eating memory), otherwise the clipboard will be emptied on
 104         exit.
 105
 106         @returns @false if the operation is unsuccessful for any reason.
 107     */
 108     bool Flush();
 109
 110     /**
 111         Call this function to fill @a data with data on the clipboard, if
 112         available in the required format. Returns @true on success.
 113     */
 114     bool GetData(wxDataObject& data);
 115
 116     /**
 117         Returns @true if the clipboard has been opened.
 118     */
 119     bool IsOpened() const;
 120
 121     /**
 122         Returns @true if there is data which matches the data format of the
 123         given data object currently @b available on the clipboard.
 124
 125         @todo The name of this function is misleading. This should be renamed
 126               to something that more accurately indicates what it does.
 127     */
 128     bool IsSupported(const wxDataFormat& format);
 129
 130     /**
 131         Returns @true if we are using the primary selection, @false if
 132         clipboard one.
 133
 134         @see UsePrimarySelection()
 135     */
 136     bool IsUsingPrimarySelection() const;
 137
 138     /**
 139         Call this function to open the clipboard before calling SetData() and
 140         GetData().
 141
 142         Call Close() when you have finished with the clipboard. You should keep
 143         the clipboard open for only a very short time.
 144
 145         @returns @true on success. This should be tested (as in the sample
 146                  shown above).
 147     */
 148     bool Open();
 149
 150     /**
 151         Call this function to set the data object to the clipboard. This
 152         function will clear all previous contents in the clipboard, so calling
 153         it several times does not make any sense.
 154
 155         After this function has been called, the clipboard owns the data, so do
 156         not delete the data explicitly.
 157
 158         @see AddData()
 159     */
 160     bool SetData(wxDataObject* data);
 161
 162     /**
 163         On platforms supporting it (all X11-based ports), wxClipboard uses the
 164         CLIPBOARD X11 selection by default. When this function is called with
 165         @true, all subsequent clipboard operations will use PRIMARY selection
 166         until this function is called again with @false.
 167
 168         On the other platforms, there is no PRIMARY selection and so all
 169         clipboard operations will fail. This allows to implement the standard
 170         X11 handling of the clipboard which consists in copying data to the
 171         CLIPBOARD selection only when the user explicitly requests it (i.e. by
 172         selecting the "Copy" menu command) but putting the currently selected
 173         text into the PRIMARY selection automatically, without overwriting the
 174         normal clipboard contents with the currently selected text on the other
 175         platforms.
 176     */
 177     void UsePrimarySelection(bool primary = true);
 178 };
 179