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 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