From 448dcd4157e275bd692e9250ab897eab223f90eb Mon Sep 17 00:00:00 2001 From: jrand Date: Sun, 18 Aug 2002 04:10:29 +0000 Subject: [PATCH] Complete the list of usecases for BPropertyInfo. git-svn-id: file:///srv/svn/repos/haiku/trunk/current@801 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- .../app/usecases/BPropertyInfoUseCases.html | 68 ++++++++++++++++--- 1 file changed, 58 insertions(+), 10 deletions(-) diff --git a/docs/develop/app/usecases/BPropertyInfoUseCases.html b/docs/develop/app/usecases/BPropertyInfoUseCases.html index 315cab1bc4..40bd0d7a36 100644 --- a/docs/develop/app/usecases/BPropertyInfoUseCases.html +++ b/docs/develop/app/usecases/BPropertyInfoUseCases.html @@ -1,5 +1,5 @@ - + BPropertyInfo Use Cases and Implementation Details @@ -37,17 +37,32 @@ made it into the BeBook. For the latest, refer to the
    -

  1. 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.

    2. +

  2. Construction 1: 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).

    3. + +

  3. Construction 2: 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.

    4. + +

  4. Construction 3: 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.

    5. + +

  5. Construction 4: 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.

  6. 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.

    7. +BPropertyInfo class performs a "free()" on the pointers passed in at construction time and all +pointers contained within these structures.

  7. 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.

    8. @@ -77,7 +92,40 @@ is of type B_PROPERTY_INFO_TYPE.

  8. Allows Type Code: 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.

    9. +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).

    + +

  9. Flattened Size: 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.

    10. + +

  10. Flatten: 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.

    11. + +

  11. Unflatten: 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.

    12. + +

  12. Print To Stream: 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.

    13. + +

  13. Find Match: 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.