# The Application Kit: BPropertyInfo

Derived from: public BFlattenable

Declared in: be/app/PropertyInfo.h

Library: libbe.so

## Overview

BPropertyInfo is a simple class that manages scripting. A program describes its scripting interface to a BPropertyInfo object through an array of property_info structures, with each entry describing a piece of the scripting suite. The structure definition:

       struct property_info {
          char *name;
          uint32 commands[10];
          uint32 specifiers[10];
          char *usage;
          uint32 extra_data;
       };

- name provides the name of the property this structure describes.

- commands is a zero-terminated array of commands understood by the property, i.e. `B_GET_PROPERTY`. If the first element is 0, it represents a wildcard matching all possible commands.

- specifiers is a zero-terminated array of the specifiers understood by the property, i.e. `B_DIRECT_SPECIFIER`. If the first element is 0, it represents a wildcard matching all possible specifiers.

- usage gives a human-readable string describing the property and its allowable commands and specifiers.

- extra_data is an area free for general use; the operating system does not touch its contents.

A BPropertyInfo is instantiated by passing a zero-terminated array of property_info to its constructor. A typical initialization of BPropertyInfo looks like:

       static property_info prop_list[] = {
          { "duck", {B_GET_PROPERTY, B_SET_PROPERTY, 0},
          {B_DIRECT_SPECIFIER, B_INDEX_SPECIFIER, 0}, "get or set duck"},
          { "head", {B_GET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "get head"},
          { "head", {B_SET_PROPERTY, 0}, {B_DIRECT_SPECIFIER, 0}, "set head"},
          { "feet", {0}, {0}, "can do anything with his orange feet"},
          0 // terminate list
       };

       BPropertyInfo prop_info(prop_list);

Since BPropertyInfo only stores a pointer to the array, it is important that the life span of the array is at least as long as that of the BPropertyInfo object.

Notice that BPropertyInfo doesn't impose any particular structure upon the array; in particular, not all commands and specifiers for a given property need be placed in a single entry in the array. You are free to organize your scripting suite in whatever manner is most convenient for your particular object.

BPropertyInfo is a descendant of BFlattenable, and can therefore be used to store a description of an object's supported scripting suite. This is particularly useful when overriding `GetSupportedSuites()`:

       status_t MyHandler::GetSupportedSuites(BMessage *msg)
       {
          msg->AddString("suites", "suite/vnd.Me-my_handler");
          BPropertyInfo prop_info(prop_list);
          msg->AddFlat("messages", &prop_info);
          return baseClass::GetSupportedSuites(msg);
       }

Naturally, BPropertyInfo is equally as useful in interpreting the results obtained from querying an object for its supported suites.

BPropertyInfo defines the `FindMatch()` method designed to simplify the implementation of `ResolveSpecifier()`. It returns the index of the property info matching the description given to it, or -1 if none match. This reduces `ResolveSpecifier()` in the simplest cases to:

       BHandler *MyHandler::ResolveSpecifier(BMessage *msg, int32 index,
          BMessage *spec, int32 form, const char *prop)
       {
          BPropertyInfo prop_info(prop_list);
          if (prop_info.FindMatch(msg, index, spec, form, prop) >= 0)
          return this;
          return baseClass::ResolveSpecifier(msg, index, spec, form, prop);
       }

Of course, for more complicated objects, `ResolveSpecifier()` may need to set the target handler to an object other than itself, so more processing may be required. In those cases, the object can use the index returned by `FindMatch()` to help it determine the target of the scripting message.

## Constructor and Destructor

### BPropertyInfo()

          BPropertyInfo(property_info *p = NULL, bool free_on_delete = false)

Initializes the object with the specified zero-terminated array p of property_info. Passing `true` in free_on_delete instructs the object to free the memory associated with the property_info when the object is destroyed. BPropertyInfo does not copy the array, so it is important that the array is not deleted or otherwise destroyed while the BPropertyInfo is in use.

### ~BPropertyInfo()

          ~BPropertyInfo()

If free_on_delete set to `true` in the constructor, the destructor frees all memory associated with the property_info. Otherwise, does nothing.

## Member Functions

### FindMatch()

          int32 FindMatch(BMessage *msg, int32 index, BMessage *spec, int32 form,
             const char *prop, void *data = NULL) const

Passed a property name in prop, a specifier in form, and a command in msg->what, searches the property_info array for an item supporting the specified scripting request. If index is nonzero, then `FindMatch()` only searches those property_info structures with the wildcard command (first element of command array equal to 0). Otherwise, it searches through all available property_info structures for a match. Returns an index to the property_info array if a match was found and -1 otherwise.

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.