1/*
2 * Copyright 2011-2014 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Gabe Yoder, gyoder@stny.rr.com
7 *		John Scipione, jscipione@gmail.com
8 * 
9 * Corresponds to:
10 *		headers/os/app/Clipboard.h	 hrev47355
11 *		src/kits/app/Clipboard.cpp	 hrev47355
12 */
13
14
15/*!
16	\file Clipboard.h
17	\ingroup app
18	\ingroup libbe
19	\brief Provides the BClipboard class.
20*/
21
22
23/*!
24	\var be_clipboard
25	\brief Global system clipboard object.
26
27	\since BeOS R3
28*/
29
30
31/*!
32	\class BClipboard
33	\ingroup app
34	\ingroup libbe
35	\brief Used for short-term data storage between documents and
36		applications via copy and paste operations.
37
38	Clipboards are differentiated by their name. In order for two
39	applications to share a clipboard they simply have to create a
40	BClipboard object with the same name. However, it is rarely necessary
41	to create your own clipboard, instead you can use the \c be_clipboard
42	system clipboard object.
43
44	\remark To access the system clipboard without a BApplication object,
45	create a BClipboard object with the name "system". You should avoid
46	creating a custom clipboard with the name "system" for your own use.
47
48	To access the clipboard data call the Data() method. The BMessage object
49	returned by the Data() method has the following properties:
50		- The \c what value is unused.
51		- The clipboard data is stored in a message field typed as
52			\c B_MIME_TYPE.
53		- The MIME type of the data is used as the name of the field that
54			holds the data.
55		- Each field in the data message contains the same data with a
56			different format.
57
58	To read and write to the clipboard you must first lock the BClipboard
59	object. If you fail to lock the BClipboard object then the Data() method
60	will return \c NULL instead of a pointer to a BMessage object.
61
62	Below is an example of reading a string from the system clipboard.
63\code
64const char *string;
65int32 stringLen;
66if (be_clipboard->Lock()) {
67	// Get the clipboard BMessage
68	BMessage *clip = be_clipboard->Data();
69
70	// Read the string from the clipboard data message
71	clip->FindData("text/plain", B_MIME_TYPE, (const void **)&string,
72		&stringLen);
73
74	be_clipboard->Unlock();
75} else
76	fprintf(stderr, "could not lock clipboard.\n");
77\endcode
78
79	Below is an example of writing a string to the system clipboard.
80\code
81const char* string = "Some clipboard data";
82
83if (be_clipboard->Lock()) {
84	// Clear the clipboard data
85	be_clipboard->Clear();
86
87	// Get the clipboard data message
88	BMessage *clip = be_clipboard->Data();
89
90	// Write string data to the clipboard data message
91	clip->AddData("text/plain", B_MIME_TYPE, string, strlen(string));
92
93	// Commit the data to the clipboard
94	status = be_clipboard->Commit();
95	if (status != B_OK)
96		fprintf(stderr, "could not commit data to clipboard.\n");
97
98	be_clipboard->Unlock();
99} else
100	fprintf(stderr, "could not lock clipboard.\n");
101\endcode
102
103	\since BeOS R3
104*/
105
106
107/*!
108	\fn BClipboard::BClipboard(const char* name, bool transient = false)
109	\brief Create a BClipboard object with the given \a name.
110
111	If the \a name parameter is \c NULL then the "system" BClipboard object
112	is constructed instead.
113
114	\param name The \a name of the clipboard.
115	\param transient If \c true, lose data after a reboot (currently unused).
116
117	\since BeOS R3
118*/
119
120
121/*!
122	\fn BClipboard::~BClipboard()
123	\brief Destroys the BClipboard object. The clipboard data is not destroyed.
124
125	\since BeOS R3
126*/
127
128
129/*!
130	\fn const char* BClipboard::Name() const
131	\brief Returns the name of the BClipboard object.
132
133	\returns The name of the clipboard.
134
135	\since BeOS R3
136*/
137
138
139/*!
140	\name Commit Count
141*/
142
143
144//! @{
145
146
147/*!
148	\fn uint32 BClipboard::LocalCount() const
149	\brief Returns the (locally cached) number of commits to the clipboard.
150
151	The returned value is the number of successful Commit() invocations for
152	the clipboard represented by this object, either invoked on this object
153	or another (even from another application). This method returns a locally
154	cached value, which might already be obsolete. For an up-to-date value
155	use SystemCount().
156
157	\return The number of commits to the clipboard.
158
159	\sa SystemCount()
160
161	\since BeOS R5
162*/
163
164
165/*!
166	\fn uint32 BClipboard::SystemCount() const
167	\brief Returns the number of commits to the clipboard.
168
169	The returned value is the number of successful Commit() invocations for
170	the clipboard represented by this object, either invoked on this object
171	or another (even from another application). This method retrieves the
172	value directly from the system service managing the clipboards, so it is
173	more expensive, but more up-to-date than LocalCount(), which returns a
174	locally cached value.
175
176	\return The number of commits to the clipboard.
177
178	\sa LocalCount()
179
180	\since BeOS R5
181*/
182
183
184//! @}
185
186
187/*!
188	\name Monitoring
189*/
190
191
192//! @{
193
194
195/*!
196	\fn status_t BClipboard::StartWatching(BMessenger target)
197	\brief Start watching the BClipboard object for changes.
198
199	When a change in the clipboard occurs, most like as the result of a cut
200	or copy action, a \a B_CLIPBOARD_CHANGED message is sent to \a target.
201
202	\retval B_OK Everything went fine.
203	\retval B_BAD_VALUE \a target is invalid.
204	\retval B_ERROR An error occured.
205
206	\sa StopWatching()
207
208	\since BeOS R5
209*/
210
211
212/*!
213	\fn status_t BClipboard::StopWatching(BMessenger target)
214	\brief Stop watching the BClipboard object for changes.
215
216	\retval B_OK Everything went fine.
217	\retval B_BAD_VALUE \a target is invalid.
218	\retval B_ERROR An error occurred.
219
220	\sa StartWatching()
221
222	\since BeOS R5
223*/
224
225
226//! @}
227
228
229/*!
230	\name Locking
231*/
232
233
234//! @{
235
236
237/*!
238	\fn bool BClipboard::Lock()
239	\brief Locks the clipboard so that no other tread can read from it or
240	       write to it.
241
242	You should call Lock() before reading or writing to the clipboard.
243
244	\returns \c true if the clipboard was locked, \c false otherwise.
245
246	\sa Unlock()
247
248	\since BeOS R3
249*/
250
251
252/*!
253	\fn void BClipboard::Unlock()
254	\brief Unlocks the clipboard.
255
256	\sa Lock()
257
258	\since BeOS R3
259*/
260
261
262/*!
263	\fn bool BClipboard::IsLocked() const
264	\brief Returns whether or not the clipboard is locked.
265
266	\returns \c true if the clipboard is locked, \c false if it is unlocked.
267
268	\since BeOS R5
269*/
270
271
272//! @}
273
274
275/*!
276	\name Clipboard Data Transaction
277*/
278
279
280//! @{
281
282
283/*!
284	\fn status_t BClipboard::Clear()
285	\brief Clears out all data from the clipboard.
286
287	You should call Clear() before adding new data to the BClipboard object.
288
289	\return A status code.
290	\retval B_OK Everything went find.
291	\retval B_NOT_ALLOWED The clipboard is not locked.
292	\retval B_NO_MEMORY Ran out of memory initializing the data message.
293	\retval B_ERROR Another error occurred.
294
295	\since BeOS R3
296*/
297
298
299/*!
300	\fn status_t BClipboard::Commit()
301	\brief Commits the clipboard data to the BClipboard object.
302
303	\return A status code.
304	\retval B_OK Everything went find.
305	\retval B_NOT_ALLOWED The clipboard is not locked.
306	\retval B_ERROR Another error occurred.
307
308	\since BeOS R3
309*/
310
311
312/*!
313	\fn status_t BClipboard::Commit(bool failIfChanged)
314	\brief Commits the clipboard data to the BClipboard object with the
315		option to fail if there is a change to the clipboard data.
316
317	\param failIfChanged Whether or not to fail to commit the changes
318		if there is a change in the clipboard data.
319
320		\return A status code.
321	\retval B_OK Everything went find.
322	\retval B_NOT_ALLOWED The clipboard is not locked.
323	\retval B_ERROR Another error occurred.
324
325	\since BeOS R5
326*/
327
328
329/*!
330	\fn status_t BClipboard::Revert()
331	\brief Reverts the clipboard data.
332
333	The method should be used in the case that you have made a change to the
334	clipboard data message and then decide to revert the change instead of
335	committing it.
336
337	\return A status code.
338	\retval B_OK Everything went find.
339	\retval B_NOT_ALLOWED The clipboard is not locked.
340	\retval B_NO_MEMORY Ran out of memory initializing the data message.
341	\retval B_ERROR Another error occurred.
342
343	\since BeOS R5
344*/
345
346
347//! @}
348
349
350/*!
351	\name Clipboard Data Message
352*/
353
354
355//! @{
356
357
358/*!
359	\fn BMessenger BClipboard::DataSource() const
360	\brief Gets a BMessenger object targeting the application that last
361		modified the clipboard.
362
363	The clipboard object does not need to be locked to call this method.
364
365	\returns A BMessenger object that targets the application that last
366		modified the clipboard.
367
368	\since BeOS R3
369*/
370
371
372/*!
373	\fn BMessage* BClipboard::Data() const
374	\brief Gets a pointer to the BMessage object that holds the clipboard
375		data.
376
377	If the BClipboard object is not locked this method returns \c NULL.
378
379	\returns A pointer to the BMessage object that holds the clipboard
380		data or \c NULL if the clipboard is not locked.
381
382	\since BeOS R3
383*/
384
385
386//! @}
387