1<HTML> 2<HEAD> 3<TITLE>BClipboard Use Cases and Implementation Details</TITLE> 4</HEAD> 5 6<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF"> 7 8<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1"> 9 10<H1>BClipboard Use Cases and Implementation Details:</H1> 11 12<P>This document describes the BClipboard interface and some basics of how it is implemented. 13The document has the following sections:</P> 14 15<OL> 16<LI><A HREF="#interface">BClipboard Interface</A></LI> 17<LI><A HREF="#usecases">BClipboard Use Cases</A></LI> 18<LI><A HREF="#implement">BClipboard Implementation</A></LI> 19</OL> 20 21<A NAME="interface"></A><H2>BClipboard Interface:</H2> 22 23<P>The BClipboard class provides an interface to a named, system-wide, temporary storage resource. 24Access to the system clipboard is provided by the be_clipboard variable provided by a BApplication object (or by constructing a clipboard with the name "system"). 25The best source of information for the BClipboard interface can be found 26<A HREF="https://www.haiku-os.org/legacy-docs/bebook/BClipboard.html">here in the Be Book</A>. 27</P> 28 29<A NAME="usecases"></A><H2>BClipboard Use Cases:</H2> 30 31<P>The following use cases cover the BClipboard functionality:</P> 32 33<OL> 34<LI><P><B>Construction:</B> A BClipboard will accept one or two arguments to construction. 35A name is required for identifying the clipboard. The discard argument indicates whether the 36clipboard data should be discarded between boots. Te discard argument defaults to false, however 37this is meaningless since functionality has not been implemented to maintain clipboard data 38between boots. 39After construction, the queue is empty.</P></LI> 40 41<LI><P><B>Destruction:</B> The destructor destroys the BClipboard object, however the system-wide clipboard itself is unaffected.</P></LI> 42 43<LI><P><B>Writing to clipboard 1:</B> 44The normal procedure for writing data consists of the following: locking the clipboard via Lock(), clearing the 45data via Clear(), adding data to the clipboard message, committing the data via Commit(), and unlocking the 46clipboard via Unlock(). 47</P></LI> 48 49<LI><P><B>Writing to clipboard 2:</B> 50The data which is to be written is not added directly to the BClipboard object, but is added to the data 51message for the BClipboard. The message is obtained by calling BClipboard::Data(). Data is added in fields 52of type B_MIME_TYPE. The name of the field corresponds to the MIME type of the data. If multiple fields are 53added, they should contain the same data, but formatted for different MIME types. 54</P></LI> 55 56<LI><P><B>Writing to clipboard 3:</B> 57In the event that one wishes to back out of writing process before calling Commit(), Revert() must be called. 58Otherwise, the changes to the clipboard remain in the BClipboard object. 59</P></LI> 60 61<LI><P><B>Reading from clipboard 1:</B> 62The normal procedure for reading data consists of the following: locking the clipboard via Lock(), obtaining 63the data from the clipboards data message, and unlocking the clipboard via Unlock(). 64</P></LI> 65 66<LI><P><B>Reading from clipboard 2:</B> 67The data message is obtained from a call to BClipboard::Data(). Data is obtained from the message by using 68BMessage::FindData for a specified MIME type. 69</P></LI> 70 71<LI><P><B>Reading from clipboard 3:</B> 72The data is uploaded from the system when Lock() is called, therefore any data which is written to the clipboard 73between the calls to Lock() and Data() will not be included in the data message. 74</P></LI> 75 76<LI><P><B>Reading from clipboard 4:</B> 77It is permissible to Unlock() the clipboard before calling FindData on the data message. 78</P></LI> 79 80<LI><P><B>Clearing:</B> 81The Clear() function is used to remove all data from the clipboard and is used before adding new data which is 82to be written to the clipboard. Clear() returns B_ERROR if the BClipboard is not locked, and returns B_OK if 83it is locked. 84</P></LI> 85 86<LI><P><B>Committing:</B> 87The Commit() function is used to upload data from the BClipboard to the system. The data is immediately 88available to other applications once Commit() has been called. Commit() returns B_ERROR if the BClipboard 89is not locked, and returns B_OK if it is locked. 90</P></LI> 91 92<LI><P><B>Revert:</B> 93The Revert() function is used to synchronize the data in the BClipboard to the system. This is only needed in 94case one begins to modify the data message and wishes to back out of the changes. Revert() returns B_ERROR if 95the BClipboard is not locked, and returns B_OK if it is locked. 96</P></LI> 97 98<LI><P><B>Accessing data:</B> 99Data() is used to obtain a pointer to the BClipboard's data message. One is expected to read and write data 100directly to the message, but the message must not be freed or dispatched. Data() returns NULL if the 101BClipboard is not locked. 102</P></LI> 103 104<LI><P><B>Accessing a data source:</B> 105DataSource() is used to obtain a BMessenger pointed at the BApplication which last committed data to the 106clipboard. There is no requirement for the the BClipboard to be locked when calling DataSource(). 107</P></LI> 108 109<LI><P><B>Obtaining a count:</B> 110The count refers to the number of times that data has been uploaded to the clipboard. 111There are two count functions. SystemCount() returns an up to date count which is obtained from the system. 112Count() returns a cached count. The cached count is set to zero upon creation 113of the BClipboard, and is updated when Lock() or Commit() is called. 114</P></LI> 115 116<LI><P><B>Locking:</B> 117Lock() is used to upload data from the system into the BClipboard object and prevent other threads in the 118application from using it. It must be called before reading or writing data to the BClipboard. It blocks 119if the BClipboard is already locked. The return value is true if the BClipboard is successfully locked, or 120false if the BClipboard was deleted while Lock() was blocked. 121</P></LI> 122 123<LI><P><B>Unlocking:</B> 124Unlock() is used to unlock the BClipboard and allow other threads in the application to use it. 125</P></LI> 126 127<LI><P><B>Checking lock status:</B> 128IsLocked() returns true if the BClipboard is locked by the current thread, and false if it is not lockedi or is locked by another thread. 129</P></LI> 130 131<LI><P><B>Checking clipboard name:</B> 132Name() returns a string containing the name of the clipboard. It is not necessary for the BClipboard to be 133locked when calling Name(). 134</P></LI> 135 136<LI><P><B>Watching a clipboard:</B> 137StartWatching and StopWatching are used to enable and disable watching of a clipboard. When the clipboard is 138changed, a B_CLIPBOARD_CHANGED message is sent to the target specified in the call to StartWatching. 139</P></LI> 140 141</OL> 142 143<A NAME="implement"></A><H2>BClipboard Implementation:</H2> 144 145<P> 146The BClipboard class is implemented via a message passing system between the BClipboard, the Registrar, and 147the Clipboard Handler associated with the Registrar. Details of the message passing protocol are listed in the 148Registrar documentation. 149</P> 150 151</BODY> 152</HTML> 153 154 155