interface/wx/clipbrd.h

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