This document describes the BPropertyInfo interface and some basics of how it is implemented. The document has the following sections:
The BPropertyInfo class is a simple class for describing the scripting interface which a BHandler provides. It makes implementing the ResolveSpecifier() hook function easier to implement. One source of information for the BPropertyInfo interface can be found here in the Be Book. Unfortunately, details of some changes to this interface introduced in BeOS 4 does not seem to have made it into the BeBook. For the latest, refer to the PropertyInfo.h header file or the BeOS 4 Developer Release Notes.
The following use cases cover the BPropertyInfo functionality:
Construction 1: A BPropertyInfo can be created with 0 to 3 construction arguments. With no arguments, the BPropertyInfo has no "property_info" or "value_info" structures. If one argument is specified, it must be a pointer to the property_info structure for the BPropertyInfo. If two arguments are specified, the first is the property_info pointer and the second is the value_info structure. If three arguments are specified, the first two are the same as indicated and the third is a flag which indicates that the BPropertyInfo class should "delete[]" the passed in pointers on destruction if true.
Destruction: On destruction, a BPropertyInfo class does nothing unless the third argument (free_on_delete flag) at construction was true. If this argument was true, the BPropertyInfo class performs a "delete[]" on the pointers passed in at construction time.
Properties: The Properties() member function returns the first argument passed in at construction time of the BPropertyInfo or NULL if it was constructed with no arguments.
Values: The Values() member function returns the second argument passed in at construction time of the BPropertyInfo or NULL if it was constructed with one or fewer arguments.
Count Properties: The CountProperties() member function returns the number of elements in the NULL terminated array of property_info structures passed in as the first argument at construction time. If the BPropertyInfo class was constructed with no arguments, 0 is returned.
Count Values: The CountValues() member function returns the number of elements in the NULL terminated array of value_info structures passed in as the second argument at construction time. If the BPropertyInfo class was constructed with one or fewer arguments, 0 is returned.
There is a key difference between the OpenBeOS BPropertyInfo class and the Be implementation is support for BeOS R3 compiled executables. The elements in the property_info structure changed in R4 versus the one which was used in R3. Be did the following to handle this:
For the OpenBeOS implementation, we have decided not to implement this R3 compatibility at this time but we are not going to rule it out. The header file for BPropertyInfo will be changed to "remove" the R3 compatibility interfaces using an "ifdef R3_compatible". The interfaces will still appear to the human reader but not be there as far as the compiler is concerned. If we revise out decision in the future, it will be a simple matter of removing the ifdefs and implement these R3 compatibility interfaces. For now, we have decided not to do this because:
The following is some information from Marc Flerackers sent in a series of emails which describes his investigation into how BPropertyInfo instances are flattened. Note that the implementation is very much based Marc's implementation elluded to in these messages:
I spend this morning some time to check how a BPropertyInfo is flattened, here's the result for BControl (not such a good choice as there are no compound types, however I added at the bottom how the layout looks if there are). I'm implementing this now in my own BPropertyInfo class. How is the OBOS BPropertyInfo class going BTW?
// Header
4 6 chunk count
4 1 version
// Start of property_info chunks, without types
8 "Enabled" name
58 "" usage ("Returns whether or not the BControl is currently enabled.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
8 "Enabled" name
34 "" usage ("Enables or disables the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Label" name
30 "" usage ("Returns the BControl's label.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Label" name
32 "" usage ("Sets the label of the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Value" name
30 "" usage ("Returns the BControl's value.")
4 0 extra_data
4 PGET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
6 "Value" name
32 "" usage ("Sets the value of the BControl.")
4 0 extra_data
4 PSET commands
4 0 end commands list
4 1 specifiers
4 0 end specifiers list
// Start of property_info chunks, only types
4 BOOL type
4 0 end type list
4 0 end compound list
4 BOOL type
4 0 end type list
4 0 end compound list
4 CSTR type
4 0 end type list
4 0 end compound list
4 LONG type
4 0 end type list
4 0 end compound list
4 LONG type
4 0 end type list
4 0 end compound list
If there would have been compound types, the layout of the type chunks would be like this
4 BOOL type 4 0 end type list 5 "name" compound name 4 LONG compound type 4 0 end compound list
Layout of a flattened BPropertyInfo with compound members. Value info is still missing, I will look at it when I implement support for it in my BPropertyInfo class. BTabView and BRadioButton are coming to cvs soon BTW, I only have to find some time to write decent Draw functions ^_^.
// Header 4 3 chunk count 4 1 version // Start of property_info chunks, without types 7 "Suites" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list 10 "Messenger" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list 13 "InternalName" name 1 0 usage 4 0 extra_data 4 PGET commands 4 0 end commands list 4 1 specifiers 4 0 end specifiers list // Start of property_info chunks, only types 4 0 end type list 7 "suites" compound name 4 CSTR compound type 4 0 end compound sub list 9 "messages" compound name 4 SCTD compound type 4 0 end compound sub list 4 0 end compound list 4 MSNG type 4 0 end type list 4 0 end compound list 4 CSTR type 4 0 end type list 4 0 end compound list
Some updated information about the flattened BPropertyInfo layout for people who are interested ^_^.
The header contains flags, not a version flattened header 4 count 4 flags 0x1 : property_info structs are present 0x2 : value_info structs are present flattened value_info chunks are appended at the end as follows a small header 4 count for every value_info 2 kind 4 value x name x usage 4 extra_data where x is strlen + 1 of course.
Value info structs are used to publish information about non-Be types and scripting commands btw.
I tested my code against the Be implementation, and the flattened data matches.