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