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	@wxheader{clipbrd.h}
	18
	19	A class for manipulating the clipboard.
	20
	21	To use the clipboard, you call member functions of the global
	22	::wxTheClipboard object.
	23
	24	See the @ref overview_dataobject for further information.
	25
	26	Call wxClipboard::Open() to get ownership of the clipboard. If this
	27	operation returns @true, you now own the clipboard. Call
	28	wxClipboard::SetData() to put data on the clipboard, or
	29	wxClipboard::GetData() to retrieve data from the clipboard. Call
	30	wxClipboard::Close() to close the clipboard and relinquish ownership. You
	31	should keep the clipboard open only momentarily.
	32
	33	For example:
	34
	35	@code
	36	// Write some text to the clipboard
	37	if (wxTheClipboard->Open())
	38	{
	39	// This data objects are held by the clipboard,
	40	// so do not delete them in the app.
	41	wxTheClipboard->SetData( new wxTextDataObject("Some text") );
	42	wxTheClipboard->Close();
	43	}
	44
	45	// Read some text
	46	if (wxTheClipboard->Open())
	47	{
	48	if (wxTheClipboard->IsSupported( wxDF_TEXT ))
	49	{
	50	wxTextDataObject data;
	51	wxTheClipboard->GetData( data );
	52	wxMessageBox( data.GetText() );
	53	}
	54	wxTheClipboard->Close();
	55	}
	56	@endcode
	57
	58	@library{wxcore}
	59	@category{dnd}
	60
	61	@see @ref overview_dnd, @ref overview_dataobject, wxDataObject
	62	*/
	63	class wxClipboard : public wxObject
	64	{
	65	public:
	66	/**
	67	Default constructor.
	68	*/
	69	wxClipboard();
	70
	71	/**
	72	Destructor.
	73	*/
	74	~wxClipboard();
	75
	76	/**
	77	Call this function to add the data object to the clipboard. You may
	78	call this function repeatedly after having cleared the clipboard using
	79	Clear().
	80
	81	After this function has been called, the clipboard owns the data, so do
	82	not delete the data explicitly.
	83
	84	@see SetData()
	85	*/
	86	bool AddData(wxDataObject* data);
	87
	88	/**
	89	Clears the global clipboard object and the system's clipboard if
	90	possible.
	91	*/
	92	void Clear();
	93
	94	/**
	95	Call this function to close the clipboard, having opened it with
	96	Open().
	97	*/
	98	void Close();
	99
	100	/**
	101	Flushes the clipboard: this means that the data which is currently on
	102	clipboard will stay available even after the application exits
	103	(possibly eating memory), otherwise the clipboard will be emptied on
	104	exit.
	105
	106	@return @false if the operation is unsuccessful for any reason.
	107	*/
	108	bool Flush();
	109
	110	/**
	111	Call this function to fill @a data with data on the clipboard, if
	112	available in the required format. Returns @true on success.
	113	*/
	114	bool GetData(wxDataObject& data);
	115
	116	/**
	117	Returns @true if the clipboard has been opened.
	118	*/
	119	bool IsOpened() const;
	120
	121	/**
	122	Returns @true if there is data which matches the data format of the
	123	given data object currently @b available on the clipboard.
	124
	125	@todo The name of this function is misleading. This should be renamed
	126	to something that more accurately indicates what it does.
	127	*/
	128	bool IsSupported(const wxDataFormat& format);
	129
	130	/**
	131	Returns @true if we are using the primary selection, @false if
	132	clipboard one.
	133
	134	@see UsePrimarySelection()
	135	*/
	136	bool IsUsingPrimarySelection() const;
	137
	138	/**
	139	Call this function to open the clipboard before calling SetData() and
	140	GetData().
	141
	142	Call Close() when you have finished with the clipboard. You should keep
	143	the clipboard open for only a very short time.
	144
	145	@return @true on success. This should be tested (as in the sample
	146	shown above).
	147	*/
	148	bool Open();
	149
	150	/**
	151	Call this function to set the data object to the clipboard. This
	152	function will clear all previous contents in the clipboard, so calling
	153	it several times does not make any sense.
	154
	155	After this function has been called, the clipboard owns the data, so do
	156	not delete the data explicitly.
	157
	158	@see AddData()
	159	*/
	160	bool SetData(wxDataObject* data);
	161
	162	/**
	163	On platforms supporting it (all X11-based ports), wxClipboard uses the
	164	CLIPBOARD X11 selection by default. When this function is called with
	165	@true, all subsequent clipboard operations will use PRIMARY selection
	166	until this function is called again with @false.
	167
	168	On the other platforms, there is no PRIMARY selection and so all
	169	clipboard operations will fail. This allows to implement the standard
	170	X11 handling of the clipboard which consists in copying data to the
	171	CLIPBOARD selection only when the user explicitly requests it (i.e. by
	172	selecting the "Copy" menu command) but putting the currently selected
	173	text into the PRIMARY selection automatically, without overwriting the
	174	normal clipboard contents with the currently selected text on the other
	175	platforms.
	176	*/
	177	void UsePrimarySelection(bool primary = true);
	178	};
	179