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".

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:

int32 CountEntries(const char *name)
    int32 count;
    BMessage message, reply;

    // form scripting request
    message.what = B_COUNT_PROPERTIES;
    message.AddSpecifier("Window", name);

    // deliver request and fetch response

    // return result
    if (reply.FindInt32("result", &count) == B_OK)
        return count;

    return -1;

The Tracker scripting API defines a number of ways of specifying entries in a Poses. These methods are summarized below:

B_DIRECT_SPECIFIERUsed for specifying the entire Poses or selection as appropriate.
B_INDEX_SPECIFIER"index" contains int32 index of file in the Poses. Ranges are specified with a pair of indices.
'sref'"refs" contains entry_refs of specified files.
'sprv'Refers to item immediately following file whose entry_ref is found in "data."
'snxt'Refers to item immediately preceeding file whose entry_ref is found in "data."

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 entry_refs.

The Entry Property

B_DELETE_PROPERTY'sref', B_INDEX_SPECIFIERMoves the specified entry to the Trash.
B_EXECUTE_PROPERTY'sref', B_INDEX_SPECIFIERPerform the equivalent action of opening the specified items in the Tracker.
B_GET_PROPERTYB_DIRECT_SPECIFIERReturns entry_refs of all entries in current Poses.
B_GET_PROPERTYB_INDEX_SPECIFIERReturns specified entry_ref.
B_GET_PROPERTY'sprv', 'snxt'Returns entry_ref of entry prior to or following specified entry_ref. Also returns index of file in "index."

The Selection Property

B_COUNT_PROPERTIESB_DIRECT_SPECIFIERCounts the number of selected items in the Poses.
B_CREATE_PROPERTYB_DIRECT_SPECIFIERAdds items to the current selection. These can be specified as either entry_refs or int32s in the "data" array.
B_DELETE_PROPERTY'sref', B_INDEX_SPECIFIERRemoves items from the current selection.
B_GET_PROPERTYB_DIRECT_SPECIFIERReturns entry_refs of items in selection.
B_GET_PROPERTY'sprv', 'snxt'Returns entry_ref of file prior to or following given item. Returns the index of the file in "index."
B_SET_PROPERTYB_DIRECT_SPECIFIERClears the current selection and set it to the range given in "data." Also accepts entry_refs in "data" to determined the new selection.
B_SET_PROPERTY'sprv', 'snxt'Clears the current selection and sets it to the entry_refs prior to or following those specified in "data."
Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.