2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: clipbrd.h
|
2008-03-10 11:24:38 -04:00
|
|
|
// Purpose: interface of wxClipboard
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
|
|
|
// RCS-ID: $Id$
|
2010-07-13 09:29:13 -04:00
|
|
|
// Licence: wxWindows licence
|
2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
/**
|
|
|
|
The backwards compatible access macro that returns the global clipboard
|
|
|
|
object pointer.
|
|
|
|
*/
|
|
|
|
#define wxTheClipboard
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
/**
|
|
|
|
@class wxClipboard
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
A class for manipulating the clipboard.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
To use the clipboard, you call member functions of the global
|
|
|
|
::wxTheClipboard object.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
See the @ref overview_dataobject for further information.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
For example:
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@code
|
|
|
|
// Write some text to the clipboard
|
2008-04-08 01:34:11 -04:00
|
|
|
if (wxTheClipboard->Open())
|
|
|
|
{
|
2008-09-22 18:39:21 -04:00
|
|
|
// This data objects are held by the clipboard,
|
2008-03-08 08:52:38 -05:00
|
|
|
// so do not delete them in the app.
|
2008-04-08 01:34:11 -04:00
|
|
|
wxTheClipboard->SetData( new wxTextDataObject("Some text") );
|
|
|
|
wxTheClipboard->Close();
|
|
|
|
}
|
|
|
|
|
|
|
|
// Read some text
|
|
|
|
if (wxTheClipboard->Open())
|
|
|
|
{
|
|
|
|
if (wxTheClipboard->IsSupported( wxDF_TEXT ))
|
2008-03-08 08:52:38 -05:00
|
|
|
{
|
2008-04-08 01:34:11 -04:00
|
|
|
wxTextDataObject data;
|
|
|
|
wxTheClipboard->GetData( data );
|
|
|
|
wxMessageBox( data.GetText() );
|
2008-09-22 18:39:21 -04:00
|
|
|
}
|
2008-04-08 01:34:11 -04:00
|
|
|
wxTheClipboard->Close();
|
|
|
|
}
|
2008-03-08 08:52:38 -05:00
|
|
|
@endcode
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxcore}
|
|
|
|
@category{dnd}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-04-08 01:34:11 -04:00
|
|
|
@see @ref overview_dnd, @ref overview_dataobject, wxDataObject
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxClipboard : public wxObject
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
Default constructor.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
wxClipboard();
|
|
|
|
|
|
|
|
/**
|
|
|
|
Destructor.
|
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual ~wxClipboard();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see SetData()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool AddData(wxDataObject* data);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
Clears the global clipboard object and the system's clipboard if
|
|
|
|
possible.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual void Clear();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
Call this function to close the clipboard, having opened it with
|
|
|
|
Open().
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual void Close();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Flushes the clipboard: this means that the data which is currently on
|
2008-04-08 01:34:11 -04:00
|
|
|
clipboard will stay available even after the application exits
|
|
|
|
(possibly eating memory), otherwise the clipboard will be emptied on
|
|
|
|
exit.
|
|
|
|
|
2008-05-10 21:38:53 -04:00
|
|
|
@return @false if the operation is unsuccessful for any reason.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool Flush();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
Call this function to fill @a data with data on the clipboard, if
|
|
|
|
available in the required format. Returns @true on success.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool GetData(wxDataObject& data);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the clipboard has been opened.
|
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool IsOpened() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool IsSupported(const wxDataFormat& format);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
Returns @true if we are using the primary selection, @false if
|
|
|
|
clipboard one.
|
|
|
|
|
|
|
|
@see UsePrimarySelection()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool IsUsingPrimarySelection() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
|
|
|
|
2008-05-10 21:38:53 -04:00
|
|
|
@return @true on success. This should be tested (as in the sample
|
|
|
|
shown above).
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool Open();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see AddData()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 15:01:17 -04:00
|
|
|
virtual bool SetData(wxDataObject* data);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
On platforms supporting it (all X11-based ports), wxClipboard uses the
|
2008-04-08 01:34:11 -04:00
|
|
|
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.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-22 18:39:21 -04:00
|
|
|
virtual void UsePrimarySelection(bool primary = false);
|
2008-03-08 08:52:38 -05:00
|
|
|
};
|
2008-03-10 11:24:38 -04:00
|
|
|
|