/////////////////////////////////////////////////////////////////////////////
// Name: clipbrd.h
-// Purpose: documentation for wxClipboard class
+// Purpose: interface of wxClipboard
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+/**
+ The backwards compatible access macro that returns the global clipboard
+ object pointer.
+*/
+#define wxTheClipboard
+
/**
@class wxClipboard
@wxheader{clipbrd.h}
- A class for manipulating the clipboard. Note that this is not compatible with
- the
- clipboard class from wxWidgets 1.xx, which has the same name but a different
- implementation.
+ A class for manipulating the clipboard.
- To use the clipboard, you call member functions of the global @b wxTheClipboard
- object.
+ To use the clipboard, you call member functions of the global
+ ::wxTheClipboard object.
- See also the @ref overview_wxdataobjectoverview for further information.
+ See the @ref overview_dataobject for further information.
- Call wxClipboard::Open to get ownership of the clipboard. If this operation
- returns @true, you
- now own the clipboard. Call wxClipboard::SetData to put data
- on the clipboard, or wxClipboard::GetData to
- retrieve data from the clipboard. Call wxClipboard::Close to close
- the clipboard and relinquish ownership. You should keep the clipboard open only
- momentarily.
+ Call wxClipboard::Open() to get ownership of the clipboard. If this
+ operation returns @true, you now own the clipboard. Call
+ wxClipboard::SetData() to put data on the clipboard, or
+ wxClipboard::GetData() to retrieve data from the clipboard. Call
+ wxClipboard::Close() to close the clipboard and relinquish ownership. You
+ should keep the clipboard open only momentarily.
For example:
@code
// Write some text to the clipboard
- if (wxTheClipboard-Open())
- {
- // This data objects are held by the clipboard,
+ if (wxTheClipboard->Open())
+ {
+ // This data objects are held by the clipboard,
// so do not delete them in the app.
- wxTheClipboard-SetData( new wxTextDataObject("Some text") );
- wxTheClipboard-Close();
- }
-
- // Read some text
- if (wxTheClipboard-Open())
- {
- if (wxTheClipboard-IsSupported( wxDF_TEXT ))
+ wxTheClipboard->SetData( new wxTextDataObject("Some text") );
+ wxTheClipboard->Close();
+ }
+
+ // Read some text
+ if (wxTheClipboard->Open())
+ {
+ if (wxTheClipboard->IsSupported( wxDF_TEXT ))
{
- wxTextDataObject data;
- wxTheClipboard-GetData( data );
- wxMessageBox( data.GetText() );
- }
- wxTheClipboard-Close();
- }
+ wxTextDataObject data;
+ wxTheClipboard->GetData( data );
+ wxMessageBox( data.GetText() );
+ }
+ wxTheClipboard->Close();
+ }
@endcode
@library{wxcore}
@category{dnd}
- @seealso
- @ref overview_wxdndoverview, wxDataObject
+ @see @ref overview_dnd, @ref overview_dataobject, wxDataObject
*/
class wxClipboard : public wxObject
{
public:
/**
- Constructor.
+ Default constructor.
*/
wxClipboard();
~wxClipboard();
/**
- Call this function to add the data object to the clipboard. You may call
- this function repeatedly after having cleared the clipboard using Clear().
- After this function has been called, the clipboard owns the data, so do not
- delete
- the data explicitly.
-
+ Call this function to add the data object to the clipboard. You may
+ call this function repeatedly after having cleared the clipboard using
+ Clear().
+
+ After this function has been called, the clipboard owns the data, so do
+ not delete the data explicitly.
+
@see SetData()
*/
bool AddData(wxDataObject* data);
/**
- Clears the global clipboard object and the system's clipboard if possible.
+ Clears the global clipboard object and the system's clipboard if
+ possible.
*/
void Clear();
/**
- Call this function to close the clipboard, having opened it with Open().
+ Call this function to close the clipboard, having opened it with
+ Open().
*/
void Close();
/**
Flushes the clipboard: this means that the data which is currently on
- clipboard will stay available even after the application exits (possibly
- eating memory), otherwise the clipboard will be emptied on exit.
- Returns @false if the operation is unsuccessful for any reason.
+ clipboard will stay available even after the application exits
+ (possibly eating memory), otherwise the clipboard will be emptied on
+ exit.
+
+ @return @false if the operation is unsuccessful for any reason.
*/
bool Flush();
/**
- Call this function to fill @a data with data on the clipboard, if available in
- the required
- format. Returns @true on success.
+ Call this function to fill @a data with data on the clipboard, if
+ available in the required format. Returns @true on success.
*/
bool GetData(wxDataObject& data);
bool IsOpened() const;
/**
- Returns @true if there is data which matches the data format of the given data
- object currently @b available (IsSupported sounds like a misnomer, FIXME: better deprecate this name?) on the clipboard.
+ Returns @true if there is data which matches the data format of the
+ given data object currently @b available on the clipboard.
+
+ @todo The name of this function is misleading. This should be renamed
+ to something that more accurately indicates what it does.
*/
bool IsSupported(const wxDataFormat& format);
/**
- Returns @true if we are using the primary selection, @false if clipboard
- one.
- See @ref useprimary() UsePrimarySelection for more information.
+ Returns @true if we are using the primary selection, @false if
+ clipboard one.
+
+ @see UsePrimarySelection()
*/
bool IsUsingPrimarySelection() const;
/**
- Call this function to open the clipboard before calling SetData()
- and GetData().
- Call Close() when you have finished with the clipboard. You
- should keep the clipboard open for only a very short time.
- Returns @true on success. This should be tested (as in the sample shown above).
+ Call this function to open the clipboard before calling SetData() and
+ GetData().
+
+ Call Close() when you have finished with the clipboard. You should keep
+ the clipboard open for only a very short time.
+
+ @return @true on success. This should be tested (as in the sample
+ shown above).
*/
bool Open();
/**
- Call this function to set the data object to the clipboard. This function will
- clear all previous contents in the clipboard, so calling it several times
- does not make any sense.
- After this function has been called, the clipboard owns the data, so do not
- delete
- the data explicitly.
-
+ Call this function to set the data object to the clipboard. This
+ function will clear all previous contents in the clipboard, so calling
+ it several times does not make any sense.
+
+ After this function has been called, the clipboard owns the data, so do
+ not delete the data explicitly.
+
@see AddData()
*/
bool SetData(wxDataObject* data);
/**
On platforms supporting it (all X11-based ports), wxClipboard uses the
- CLIPBOARD X11 selection by default. When this function is called with @true
- argument, all subsequent clipboard operations will use PRIMARY selection until
- this function is called again with @false.
- On the other platforms, there is no PRIMARY selection and so all clipboard
- operations will fail. This allows to implement the standard X11 handling of the
- clipboard which consists in copying data to the CLIPBOARD selection only when
- the user explicitly requests it (i.e. by selection @c "Copy" menu
- command) but putting the currently selected text into the PRIMARY selection
- automatically, without overwriting the normal clipboard contents with the
- currently selected text on the other platforms.
+ CLIPBOARD X11 selection by default. When this function is called with
+ @true, all subsequent clipboard operations will use PRIMARY selection
+ until this function is called again with @false.
+
+ On the other platforms, there is no PRIMARY selection and so all
+ clipboard operations will fail. This allows to implement the standard
+ X11 handling of the clipboard which consists in copying data to the
+ CLIPBOARD selection only when the user explicitly requests it (i.e. by
+ selecting the "Copy" menu command) but putting the currently selected
+ text into the PRIMARY selection automatically, without overwriting the
+ normal clipboard contents with the currently selected text on the other
+ platforms.
*/
void UsePrimarySelection(bool primary = true);
};
+
projects / wxWidgets.git / blobdiff