51 lines
11 KiB
HTML
51 lines
11 KiB
HTML
<?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 - Special Topics - The Tracker</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="TheTracker.html" title="The Tracker" /><link rel="prev" href="TheTracker.html" title="The Tracker" /><link rel="next" href="TheTracker_AddOnProtocol.html" title="Add-on Protocol" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheTracker.html" title="The Tracker"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheTracker.html" title="The Tracker"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheTracker_AddOnProtocol.html" title="Add-on Protocol"><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 - Special Topics - The Tracker</div></div><div id="headerB">Prev: <a href="TheTracker.html">The Tracker</a> Up: <a href="TheTracker.html">The Tracker</a> Next: <a href="TheTracker_AddOnProtocol.html">Add-on Protocol</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="TheTracker_Scripting"></a>Scripting</h2></div></div></div><p>Each Tracker window defines a "Poses" property representing the contents
|
||
of the window. Each poses, in turn, defines the two properties "Entry"
|
||
and "Selection". An "Entry" is an item in the window, e.g. either a file
|
||
or a directory, while a "Selection" represents a selected "Entry".</p><p>When a Tracker window receives a scripting message with a "Poses"
|
||
property, it pops the current specifier off the specifier stack and then
|
||
forwards the scripting message to the view handling the "Poses" property.
|
||
From there, the "Entry" and "Selection" properties are processed. For
|
||
example, the following function returns the number of entries present in
|
||
a given Tracker window:</p><pre class="programlisting example cpp"><span class="type">int32</span> <code class="function">CountEntries</code>(<span class="type">const char *</span><code class="parameter">name</code>)
|
||
{
|
||
<span class="type">int32</span> count;
|
||
<code class="classname">BMessage</code> <code class="varname">message</code>, <code class="varname">reply</code>;
|
||
|
||
// form scripting request
|
||
<code class="varname">message</code>.<code class="varname">what</code> = <code class="constant">B_COUNT_PROPERTIES</code>;
|
||
<code class="varname">message</code>.<code class="methodname">AddSpecifier</code>("Entry");
|
||
<code class="varname">message</code>.<code class="methodname">AddSpecifier</code>("Poses");
|
||
<code class="varname">message</code>.<code class="methodname">AddSpecifier</code>("Window", <code class="varname">name</code>);
|
||
|
||
// deliver request and fetch response
|
||
<code class="classname">BMessenger</code>("application/x-vnd.Be-TRAK").<code class="methodname">SendMessage</code>(&<code class="varname">message</code>,
|
||
&<code class="varname">reply</code>);
|
||
|
||
// return result
|
||
if (<code class="varname">reply</code>.<code class="methodname">FindInt32</code>("result", &<code class="varname">count</code>) == <code class="constant">B_OK</code>)
|
||
return <code class="varname">count</code>;
|
||
|
||
return -1;
|
||
}</pre><p>The Tracker scripting API defines a number of ways of specifying entries
|
||
in a Poses. These methods are summarized below:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Specifier</th><th>Description</th></tr></thead><tbody><tr><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Used for specifying the entire Poses or selection as appropriate.</td></tr><tr><td><code class="constant">B_INDEX_SPECIFIER</code></td><td>"index" contains <span class="type">int32</span> index of file in the Poses.
|
||
Ranges are specified with a pair of indices.</td></tr><tr><td>'sref'</td><td>"refs" contains <span class="type">entry_ref</span>s of specified files.</td></tr><tr><td>'sprv'</td><td>Refers to item immediately following file whose <span class="type">entry_ref</span> is found
|
||
in "data."</td></tr><tr><td>'snxt'</td><td>Refers to item immediately preceeding file whose <span class="type">entry_ref</span> is
|
||
found in "data."</td></tr></tbody></table></div><p>Always remember that other programs (or the user) may also be adding or
|
||
removing entries to the view and selection, so do not rely upon indices
|
||
as a safe method of referring to a specific file. Instead, use
|
||
<span class="type">entry_refs</span>.</p><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="TheTracker_Scripting_Entry"></a>The Entry Property</h3></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Message</th><th>Specifiers</th><th>Description</th></tr></thead><tbody><tr><td><code class="constant">B_COUNT_PROPERTIES</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Counts entries in a Poses.</td></tr><tr><td><code class="constant">B_DELETE_PROPERTY</code></td><td>'sref', <code class="constant">B_INDEX_SPECIFIER</code></td><td>Moves the specified entry to the Trash.</td></tr><tr><td><code class="constant">B_EXECUTE_PROPERTY</code></td><td>'sref', <code class="constant">B_INDEX_SPECIFIER</code></td><td>Perform the equivalent action of opening the specified
|
||
items in the Tracker.</td></tr><tr><td><code class="constant">B_GET_PROPERTY</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Returns <span class="type">entry_ref</span>s of all entries in current Poses.</td></tr><tr><td><code class="constant">B_GET_PROPERTY</code></td><td><code class="constant">B_INDEX_SPECIFIER</code></td><td>Returns specified <span class="type">entry_ref</span>.</td></tr><tr><td><code class="constant">B_GET_PROPERTY</code></td><td>'sprv', 'snxt'</td><td>Returns <span class="type">entry_ref</span> of entry prior to or
|
||
following specified <span class="type">entry_ref</span>. Also returns index of
|
||
file in "index."</td></tr></tbody></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="TheTracker_Scripting_Selection"></a>The Selection Property</h3></div></div></div><div class="informaltable"><table border="1"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Message</th><th>Specifiers</th><th>Description</th></tr></thead><tbody><tr><td><code class="constant">B_COUNT_PROPERTIES</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Counts the number of selected items in the Poses.</td></tr><tr><td><code class="constant">B_CREATE_PROPERTY</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Adds items to the current selection. These can be specified as
|
||
either <span class="type">entry_ref</span>s or <span class="type">int32</span>s in the "data" array.</td></tr><tr><td><code class="constant">B_DELETE_PROPERTY</code></td><td>'sref', <code class="constant">B_INDEX_SPECIFIER</code></td><td>Removes items from the current selection.</td></tr><tr><td><code class="constant">B_GET_PROPERTY</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Returns <span class="type">entry_ref</span>s of items in selection.</td></tr><tr><td><code class="constant">B_GET_PROPERTY</code></td><td>'sprv', 'snxt'</td><td>Returns <span class="type">entry_ref</span> of file prior to or
|
||
following given item. Returns the index of the file in "index."</td></tr><tr><td><code class="constant">B_SET_PROPERTY</code></td><td><code class="constant">B_DIRECT_SPECIFIER</code></td><td>Clears the current selection and set it
|
||
to the range given in "data." Also accepts <span class="type">entry_ref</span>s in "data" to
|
||
determined the new selection.</td></tr><tr><td><code class="constant">B_SET_PROPERTY</code></td><td>'sprv', 'snxt'</td><td>Clears the current selection and sets it to
|
||
the <span class="type">entry_ref</span>s prior to or following those specified in "data."</td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheTracker.html">The Tracker</a> Up: <a href="TheTracker.html">The Tracker</a> Next: <a href="TheTracker_AddOnProtocol.html">Add-on Protocol</a> </div><div id="footerB"><div id="footerBL"><a href="TheTracker.html" title="The Tracker"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheTracker.html" title="The Tracker"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheTracker_AddOnProtocol.html" title="Add-on Protocol"><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>
|