interface/wx/clipbrd.h

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