nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BClipboard_Overview.html

113 lines
20 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - System Overview - The Application Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheApplicationKit_Overview.html" title="The Application Kit" /><link rel="prev" href="BApplication_Overview.html" title="BApplication" /><link rel="next" href="BCursor_Overview.html" title="BCursor" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BApplication_Overview.html" title="BApplication"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BCursor_Overview.html" title="BCursor"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - System Overview - The Application Kit</div></div><div id="headerB">Prev: <a href="BApplication_Overview.html">BApplication</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BCursor_Overview.html">BCursor</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BClipboard_Overview"></a>BClipboard</h2></div></div></div><a id="id483801" class="indexterm"></a><p>A <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>
object is an interface to a clipboard, a resource that provides
system-wide, temporary data storage. Clipboards are identified by name; if
two apps want to refer to the same clipboard, they simply create respective
<a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> objects
with the same name:</p><pre class="programlisting example cpp"><span class="comment">/* App A: This creates a clipboard named "MyClipboard". */</span>
<span class="type"><a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> *</span><code class="varname">appAclipboard</code> = new <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>("MyClipboard");
<span class="comment">/* App B: This object refers to the clipboard already created
by App A. */</span>
<span class="type"><a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> *</span><code class="varname">appBclipboard</code> = new <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>("MyClipboard");</pre><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id483898"></a>The System Clipboard</h3></div></div></div><p>In practice, you rarely need to construct your own <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> object;
instead, you use the <code class="classname">BClipboard</code> that's created for
you by your
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a> object.
This object, which you refer to through the global
<a class="link" href="BClipboard.html#BClipboard_be_clipboard" title="be_clipboard"><code class="varname">be_clipboard</code></a>
variable, accesses the default system
clipboard. Data that you write to your
<a class="link" href="BClipboard.html#BClipboard_be_clipboard" title="be_clipboard"><code class="varname">be_clipboard</code></a>
object can be read from any other app's
<a class="link" href="BClipboard.html#BClipboard_be_clipboard" title="be_clipboard"><code class="varname">be_clipboard</code></a>
For example, the cut/copy/paste operations defined by <a class="link" href="BTextView.html" title="BTextView"><code class="classname">BTextView</code></a> transfer data
through the system clipboard.</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>To access the system clipboard without creating a
<a class="link" href="BApplication.html" title="BApplication"><code class="classname">BApplication</code></a>
object, construct a <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>
object with the name "system". The system clipboard is under the
control of the user; you should only read or write the system clipboard as
a direct result of the user's actions. If you create your own clipboards
don't name them "system".</p></div></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BClipboard_Overview_The_Clipboard_Message"></a>The Clipboard Message</h3></div></div></div><p>To access a clipboard's data, you call functions on a <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> that the <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> object hands
you (through its
<a class="link" href="BClipboard.html#BClipboard_Data" title="Data()"><code class="methodname">Data()</code></a>
function). The
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
follows these conventions:</p><ul class="itemizedlist"><li><p>The <a class="link" href="BMessage.html#BMessage_what" title="what"><code class="varname">what</code></a> value is unused.</p></li><li><p>The data is stored in a message field. The field should be typed as
<code class="constant">B_MIME_TYPE</code>; the
<acronym class="acronym" title="Multi-purpose Internet Main Extensions">MIME</acronym>
type that describes the data should be used
as the name of the field that holds the data (see
"<a class="link" href="BClipboard_Overview.html#BClipboard_Overview_Writing_To_The_Clipboard" title="Writing to the Clipboard">Writing to the Clipboard</a>"
for an example).</p></li><li><p>If the <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
contains more than one field, each field should present the same data in a
different format. For example, the <span class="application">StyledEdit</span>
app writes text data in its own format (in order to encode the fonts,
colors, etc.) and also writes the data as plain
<acronym class="acronym" title="American Standard Code for Intercom and Interchange">ASCII</acronym>
text (<acronym class="acronym">MIME</acronym> type
"text/plain").</p></li></ul></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BClipboard_Overview_Writing_To_The_Clipboard"></a>Writing to the Clipboard</h3></div></div></div><p>The following annotated example shows how to write to the clipboard.</p><pre class="programlisting example cpp"><a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>* <code class="varname">clip</code> = (<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> *)NULL;
if (<code class="varname">be_clipboard</code>-&gt;<code class="methodname">Lock</code>()<a id="writeclip.lock"></a><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span>) {
<code class="varname">be_clipboard</code>-&gt;<code class="methodname">Clear</code>()<a id="writeclip.clear"></a><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span>;
if ((<code class="varname">clip</code> = <code class="methodname">be_clipboard</code>-&gt;<code class="methodname">Data</code>()<a id="writeclip.data"></a><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span>) {
<code class="varname">clip</code>-&gt;<code class="methodname">AddData</code>("text/MyFormat", <code class="constant">B_MIME_TYPE</code>, <code class="varname">myText</code>,
<code class="varname">myLength</code>)<a id="writeclip.add"></a><span class="callout"><img src="./images/callouts/4.png" alt="4" /></span>;
<code class="varname">clip</code>-&gt;<code class="methodname">AddData</code>("text/plain", <code class="constant">B_MIME_TYPE</code>, <code class="varname">asciiText</code>,
<code class="varname">asciiLength</code>);
<code class="varname">be_clipboard</code>-&gt;<code class="methodname">Commit</code>()<a id="writeclip.commit"></a><span class="callout"><img src="./images/callouts/5.png" alt="5" /></span>;
}
<code class="varname">be_clipboard</code>-&gt;<code class="methodname">Unlock</code>()<a id="writeclip.unlock"></a><span class="callout"><img src="./images/callouts/6.png" alt="6" /></span>;
}</pre><div class="calloutlist"><table summary="Callout list"><tr><td><a href="#writeclip.lock"><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span></a> </td><td><p><code class="methodname">Lock()</code> your <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> object. This
uploads data from the clipboard into your <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>'s local <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> object, and
prevents other threads in your application from accessing the <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>'s data. Note
that locking does not lock the underlying clipboard data other applications
can change the clipboard while you have your object locked.</p></td></tr><tr><td><a href="#writeclip.clear"><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span></a> </td><td><p>Prepare the <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a> for writing
by calling <code class="methodname">Clear()</code>. This erases the data that was
uploaded from the clipboard.</p></td></tr><tr><td><a href="#writeclip.data"><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span></a> </td><td><p>Call <a class="link" href="BClipboard.html#BClipboard_Data" title="Data()"><code class="methodname">Data()</code></a>
to get a pointer to the <a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>'s <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> object.</p></td></tr><tr><td><a href="#writeclip.add"><span class="callout"><img src="./images/callouts/4.png" alt="4" /></span></a> </td><td><p>Write the data by invoking <a class="link" href="BMessage.html#BMessage_AddData" title="AddData(), AddBool(), AddInt8(), AddInt16(), AddInt32(), AddInt64(), AddFloat(), AddDouble(), AddString(), AddPoint(), AddRect(), AddRef(), AddMessage(), AddMessenger(), AddPointer(), AddFlat()"><code class="methodname">AddData()</code></a>
directly on the <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>. In the example,
we write the data in two different formats.</p></td></tr><tr><td><a href="#writeclip.commit"><span class="callout"><img src="./images/callouts/5.png" alt="5" /></span></a> </td><td><p>Call
<a class="link" href="BClipboard.html#BClipboard_Commit"><code class="methodname">Commit()</code></a>
to copy your <a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
back to the clipboard. As soon as you call
<a class="link" href="BClipboard.html#BClipboard_Commit"><code class="methodname">Commit()</code></a>,
the data that you added is visible to other clipboard clients.</p></td></tr><tr><td><a href="#writeclip.unlock"><span class="callout"><img src="./images/callouts/6.png" alt="6" /></span></a> </td><td><p><a class="link" href="BClipboard.html#BClipboard_Unlock"><code class="methodname">Unlock()</code></a>
balances the
<a class="link" href="BClipboard.html#BClipboard_Lock" title="Lock(), Unlock(), IsLocked()"><code class="methodname">Lock()</code></a>.
The
<a class="link" href="BClipboard.html" title="BClipboard"><code class="classname">BClipboard</code></a>
object can now be accessed by other threads in your application.</p></td></tr></table></div><p>If you decide that you don't want to commit your changes, you should call
<a class="link" href="BClipboard.html#BClipboard_Revert"><code class="methodname">Revert()</code></a> before you unlock.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BClipboard_Overview_Reading"></a>Reading from the Clipboard</h3></div></div></div><p>Here we show how to read a simple string from the clipboard.</p><pre class="programlisting example cpp"><span class="type">const char *</span><code class="varname">text</code>;
<span class="type">int32</span> <code class="varname">textLen</code>;
<code class="classname">BMessage</code> *<code class="varname">clip</code> = (<code class="classname">BMessage</code> *)<code class="constant">NULL</code>;
if (<code class="varname">be_clipboard</code>-&gt;<code class="methodname">Lock</code>()<a id="readclip.lock"></a><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span>) {
if ((<code class="varname">clip</code> = <code class="varname">be_clipboard</code>-&gt;<code class="methodname">Data</code>())
<code class="varname">clip</code>-&gt;<code class="methodname">FindData</code>("text/plain", <code class="constant">B_MIME_TYPE</code>,
(<span class="type">const void **</span>)<code class="varname">text</code>, <code class="varname">textlen</code>)<a id="readclip.find"></a><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span>;
<code class="varname">be_clipboard</code>-<code class="methodname">Unlock</code>()<a id="readclip.unlock"></a><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span>;
}</pre><div class="calloutlist"><table summary="Callout list"><tr><td><a href="#readclip.lock"><span class="callout"><img src="./images/callouts/1.png" alt="1" /></span></a> </td><td><p>As in writing, we bracket the operation with
<a class="link" href="BClipboard.html#BClipboard_Lock" title="Lock(), Unlock(), IsLocked()"><code class="methodname">Lock()</code></a> and
<a class="link" href="BClipboard.html#BClipboard_Unlock"><code class="methodname">Unlock()</code></a>. Keep
in mind that
<a class="link" href="BClipboard.html#BClipboard_Lock" title="Lock(), Unlock(), IsLocked()"><code class="methodname">Lock()</code></a> uploads data from the
clipboard into our object. Any changes that are made to the clipboard (by
some other application) after
<a class="link" href="BClipboard.html#BClipboard_Lock" title="Lock(), Unlock(), IsLocked()"><code class="methodname">Lock()</code></a>
is called won't be seen here.</p></td></tr><tr><td><a href="#readclip.find"><span class="callout"><img src="./images/callouts/2.png" alt="2" /></span></a> </td><td><p>In this example, we only look for one hard-coded format. In a real
application, you may have a list of formats that you can look for.</p></td></tr><tr><td><a href="#readclip.unlock"><span class="callout"><img src="./images/callouts/3.png" alt="3" /></span></a> </td><td><p>It isn't necessary to examine the clipboard data before you unlock it. The
<a class="link" href="BMessage.html#BMessage_FindData" title="FindData(), FindBool(), FintInt8(), FindInt16(), FindInt32(), FindInt64(), FindFloat(), FindDouble(), FindString(), FindPoint(), FindRect(), FindRef(), FindMessage(), FindMessenger(), FindPointer(), FindFlat()"><code class="methodname">FindData()</code></a>
call could just as well have been performed after the
<a class="link" href="BClipboard.html#BClipboard_Unlock"><code class="methodname">Unlock()</code></a> call.</p></td></tr></table></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="id443769"></a>Persistence</h3></div></div></div><dl class="variablelist"><dt><span class="term">Inter-boot persistence:</span></dt><dd><p>Clipboard data does not persist between boots, the constructor provides a
persistence flag but it's currently unused.</p></dd><dt><span class="term">Intra-boot persistence:</span></dt><dd><p>Once you've created a clipboard, that clipboard will exist until you reboot
your computer. For example, let's say you design an app that creates a
clipboard called "MyClip": You launch the app, write something to
"MyClip", and then quit the app. The clipboard and the data that
you wrote to it will still exist: If you relaunch your app (or any app that
knows about "MyClip"), you can pick up the data by reading from
the "MyClip" clipboard.</p></dd></dl></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BApplication_Overview.html">BApplication</a>  Up: <a href="TheApplicationKit_Overview.html">The Application Kit</a>  Next: <a href="BCursor_Overview.html">BCursor</a> </div><div id="footerB"><div id="footerBL"><a href="BApplication_Overview.html" title="BApplication"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheApplicationKit_Overview.html" title="The Application Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BCursor_Overview.html" title="BCursor"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink