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("Entry");
    message.AddSpecifier("Poses");
    message.AddSpecifier("Window", name);

    // deliver request and fetch response
    BMessenger("application/x-vnd.Be-TRAK").SendMessage(&message,
    &reply);

    // 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:

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.