The Application Kit: BPropertyInfo

The Application Kit Table of Contents | The Application Kit Index

# BPropertyInfo

Derived from: BFlattenable

Declared in: be/app/PropertyInfo.h

Library: libbe.so

###### Summary

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

### AllowsTypeCode()

Implementation detail. See `BFlattenable::AllowsTypeCode().`

### 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. If a match is found, it fills the memory at data with the contents of the extra_data field of the match and returns the index of the match in the array. Otherwise, it returns `B_ERROR`.

### Flatten

Implementation detail. See `BFlattenable::Flatten().`

### FlattenedSize()

Implementation detail. See `BFlattenable::FlattenedSize().`

### IsFixedSize()

Implementation detail. See `BFlattenable::IsFixedSize().`

### TypeCode()

Implementation detail. See `BFlattenable::TypeCode().`

### PrintToStream()

void `PrintToStream(`void`)` const

Prints information about the BPropertyInfo to standard output.

### PropertyInfo()

const property_info *`PropertyInfo(`void`)` const

Returns the property_info list associated with the object.

### Unflatten()

Implementation detail. See `BFlattenable::Unflatten().`

The Application Kit Table of Contents | The Application Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..