Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Complete the list of usecases for BPropertyInfo.

Browse Source 
git-svn-id: file:///srv/svn/repos/haiku/trunk/current@801 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
jrand 2002-08-18 04:10:29 +00:00
parent 10f4de1259
commit 448dcd4157
1 changed files with 58 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
docs/develop/app/usecases/BPropertyInfoUseCases.html
View File

@ -1,5 +1,5 @@
<HTML>
<!-- $Id: BPropertyInfoUseCases.html,v 1.3 2002/08/08 04:13:51 jrand Exp $ -->
<!-- $Id: BPropertyInfoUseCases.html,v 1.4 2002/08/18 04:10:29 jrand Exp $ -->
<HEAD>
<TITLE>BPropertyInfo Use Cases and Implementation Details</TITLE>
</HEAD>
@ -37,17 +37,32 @@ made it into the BeBook. For the latest, refer to the
<OL>
<LI><P><B>Construction 1:</B> 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.</P></LI>
<LI><P><B>Construction 1:</B> A BPropertyInfo can be created with 0 arguments. In this case,
it will not have any property_info or value_info structures associated with it. The only
way to initialize it would be to Unflatten() a flattened BPropertyInfo instance (see Unflatten
use cases).</P></LI>
<LI><P><B>Construction 2:</B> A BPropertyInfo can be created with a single property_info argument.
In this case, there will be no value_info structure associated with it and the BPropertyInfo
will assume it does not need to de-allocate the property_info structure itself on
destruction.</P></LI>
<LI><P><B>Construction 3:</B> A BPropertyInfo can be created with a property_info argument and
a value_info argument. In this case, the BPropertyInfo will use both of these arguments to
determine its future behaviour. It will assume it does not need to de-allocate the property_info
structure or the value_info structure itself on destruction.</P></LI>
<LI><P><B>Construction 4:</B> A BPropertyInfo can be created with a property_info argument and
a value_info argument and a flag to indicate whether these structres were allocated on the heap.
If the flag is false, it will assume it does not need to de-allocate the property_info structure
or the value_info structure itself on destruction. If the flag is true, it will assume that
the property_info pointer and the value_info pointer and all pointers contained within them (ie
const char * instances) need to be free()'d when the BPropertyInfo is destructed.</P></LI>
<LI><P><B>Destruction:</B> 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.</P></LI>
BPropertyInfo class performs a "free()" on the pointers passed in at construction time and all
pointers contained within these structures.</P></LI>
<LI><P><B>Properties:</B> 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.</P></LI>
@ -77,7 +92,40 @@ is of type B_PROPERTY_INFO_TYPE.</P></LI>
<LI><P><B>Allows Type Code:</B> The AllowsTypeCode() method returns false for all passed in type
codes unless B_PROPERTY_INFO_TYPE ('SCTD') is passed in when this method returns true. This
implies that a BPropertyInfo class instance can be unflattened from flattened data of
B_PROPERTY_INFO_TYPE only.</P></LI>
B_PROPERTY_INFO_TYPE only (NOTE: the Be implementation seems to return true for all values
passed in although that doesn't seem to make much sense).</P></LI>
<LI><P><B>Flattened Size:</B> The FlattenedSize() member function retures the number of bytes
required to store a flattened version of the BPropertyInfo instance. The size will be determined
by the description of the flattened data structure described in the "implementation" section
below.</P></LI>
<LI><P><B>Flatten:</B> The Flatten() member function turns the current BPropertyInfo instance into
a series of bytes which completely describes its state so it can be recreated from it later. The
actual description of this byte representation of BPropertyInfo is described in the "implementation"
section below.</P></LI>
<LI><P><B>Unflatten:</B> The Unflatten() member function takes a passed in series of bytes and
sets the current BPropertyInfo instance into a copy of the BPropertyInfo described by those
bytes (ie a flattened version of a previous BPropertyInfo). The old state of the current
BPropertyInfo is replaced by that described by the flattened representation. The actual description
of this byte representation of BPropertyInfo is described in the "implemenation" section
below.</P></LI>
<LI><P><B>Print To Stream:</B> The PrintToStream() member function sends the current state of
the BPropertyInfo instance to standard out for debugging purpose. The actual format of this output
isn't critical but it should describe the state of the object and be easy for a developer to
understand.</P></LI>
<LI><P><B>Find Match:</B> The FindMatch() member function takes a BMessage, a specifier (in the
form of a BMessage), a specifier type (called form, ie B_DIRECT_SPECIFIER), property name and an
index. The member returns -1 if no match can be found. A match will have the "what" code of the
message (not the specifier message) in its command list or have a wildcard command. It will also
have the property name as its property name. And, the specifier type will be listed as a valid
specifier, or the property will have a wildcard specifier. Note, if the index is non-zero, then
only properties with command wildcards will be a match (a wildcard is an empty list of commands,
similarly for specifier type). On a match, the result is a 0 based offset into the array of
properties.</P></LI>
</OL>