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         Currently this method is not implemented in X11-based ports, i.e.
 106         wxGTK, wxX11 and wxMotif and always returns @false there.
 107
 108         @return @false if the operation is unsuccessful for any reason.
 109     */
 110     virtual bool Flush();
 111
 112     /**
 113         Call this function to fill @a data with data on the clipboard, if
 114         available in the required format. Returns @true on success.
 115     */
 116     virtual bool GetData(wxDataObject& data);
 117
 118     /**
 119         Returns @true if the clipboard has been opened.
 120     */
 121     virtual bool IsOpened() const;
 122
 123     /**
 124         Returns @true if there is data which matches the data format of the
 125         given data object currently @b available on the clipboard.
 126
 127         @todo The name of this function is misleading. This should be renamed
 128               to something that more accurately indicates what it does.
 129     */
 130     virtual bool IsSupported(const wxDataFormat& format);
 131
 132     /**
 133         Returns @true if we are using the primary selection, @false if
 134         clipboard one.
 135
 136         @see UsePrimarySelection()
 137     */
 138     bool IsUsingPrimarySelection() const;
 139
 140     /**
 141         Call this function to open the clipboard before calling SetData() and
 142         GetData().
 143
 144         Call Close() when you have finished with the clipboard. You should keep
 145         the clipboard open for only a very short time.
 146
 147         @return @true on success. This should be tested (as in the sample
 148                 shown above).
 149     */
 150     virtual bool Open();
 151
 152     /**
 153         Call this function to set the data object to the clipboard. This
 154         function will clear all previous contents in the clipboard, so calling
 155         it several times does not make any sense.
 156
 157         After this function has been called, the clipboard owns the data, so do
 158         not delete the data explicitly.
 159
 160         @see AddData()
 161     */
 162     virtual bool SetData(wxDataObject* data);
 163
 164     /**
 165         On platforms supporting it (all X11-based ports), wxClipboard uses the
 166         CLIPBOARD X11 selection by default. When this function is called with
 167         @true, all subsequent clipboard operations will use PRIMARY selection
 168         until this function is called again with @false.
 169
 170         On the other platforms, there is no PRIMARY selection and so all
 171         clipboard operations will fail. This allows to implement the standard
 172         X11 handling of the clipboard which consists in copying data to the
 173         CLIPBOARD selection only when the user explicitly requests it (i.e. by
 174         selecting the "Copy" menu command) but putting the currently selected
 175         text into the PRIMARY selection automatically, without overwriting the
 176         normal clipboard contents with the currently selected text on the other
 177         platforms.
 178     */
 179     virtual void UsePrimarySelection(bool primary = false);
 180
 181     /**
 182        Returns the global instance (wxTheClipboard) of the clipboard object.
 183     */
 184     static wxClipboard *Get();
 185
 186 };
 187