git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: clipbrd.h
	3	// Purpose: interface of wxClipboard
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	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	~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	bool AddData(wxDataObject* data);
	86
	87	/**
	88	Clears the global clipboard object and the system's clipboard if
	89	possible.
	90	*/
	91	void Clear();
	92
	93	/**
	94	Call this function to close the clipboard, having opened it with
	95	Open().
	96	*/
	97	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	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	bool GetData(wxDataObject& data);
	114
	115	/**
	116	Returns @true if the clipboard has been opened.
	117	*/
	118	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	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	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	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	void UsePrimarySelection(bool primary = true);
	177	};
	178