Description
A PBDOM_OBJECT serves as the base class for all the PBDOM classes. It contains all the basic methods required by derived classes. The derived classes of a PBDOM_OBJECT each inherit the base methods of a PBDOM_OBJECT, and additionally contain their own specialized methods.
Methods
PBDOM_OBJECT has the following methods:
Description
Adds a new PBDOM_OBJECT into the current PBDOM_OBJECT.
Syntax
pbdom_object_name.AddContent(pbdom_object pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_ref |
The PBDOM_OBJECT to add |
Return value
PBDOM_OBJECT.
The return value is the newly modified PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- Input argument is invalid.
Usage
When a new PBDOM_OBJECT is added to the current one, the new PBDOM_OBJECT becomes a child node of the current PBDOM_OBJECT.
See also
Description
Creates a general duplicate of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.Clone(boolean bDeep)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT. |
|
bDeep |
A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone. |
Return value
PBDOM_OBJECT. The return value is the clone of the PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Usage
The Clone method creates a general duplicate of the current PBDOM_OBJECT. If the bDeep parameter is true, a deep clone is returned; otherwise, a shallow clone is returned.
A PBDOM_OBJECT clone does not have a parent; however, it resides in the same PBDOM_DOCUMENT as its original. If the original PBDOM_OBJECT is standalone, the clone is also standalone.
If general, if bDeep is true, the Clone method recursively clones the subtree under the PBDOM_OBJECT. If bDeep is false, the Clone method clones only the PBDOM_OBJECT itself, together with as much information as possible.
Cloning is class specific
Cloning is not uniform across all PBDOM_OBJECT classes. See the documentation for each class for specific information.
Description
Detaches a PBDOM_OBJECT from its parent.
Syntax
pbdom_object_name.Detach()
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Examples
This example detaches the root element of a PBDOM_DOCUMENT called pbdom_doc from its parent object -- that is, from the PBDOM_DOCUMENT itself. Then, it attempts to obtain the parent PBDOM_OBJECT and tests whether it is null using the IsValid method:
pbdom_obj = pbdom_doc.GetRootElement()
pbdom_obj.Detach()
pbdom_parent_obj = pbdom_obj.GetParentObject()
if (not IsValid(pbdom_parent_obj)) then
MessageBox ("Invalid", "Root Element has no Parent")
end ifUsage
If the PBDOM_OBJECT has no parent, this method does nothing.
Description
Tests for the equality of a referenced PBDOM_OBJECT.
Syntax
pbdom_object_name.Equals(pbdom_object pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_ref |
The PBDOM_OBJECT to test for equality with the current PBDOM_OBJECT |
Return value
Boolean.
Returns true if the current PBDOM_OBJECT is equivalent to the input PBDOM_OBJECT, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- The input PBDOM_OBJECT is invalid. This can happen if the object has not been initialized properly or is a null object reference.
Description
Obtains an array of PBDOM_OBJECT objects, each of which is a child node of the called PBDOM_OBJECT.
Syntax
pbdom_object_name.GetContent(ref pbdom_object pbdom_object_array[ ])
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_array |
A reference to an array of PBDOM_OBJECT objects that will receive the PBDOM_OBJECT objects |
Return value
Boolean.
Returns true for success, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Usage
The returned array is passed by reference, with items in the same order in which they appear in the PBDOM_OBJECT. Any changes to any item of the array affect the actual item to which it refers.
See also
Description
Obtains the name of the current PBDOM_OBJECT. The returned string depends on the type of DOM Object that is contained within a PBDOM_OBJECT.
|
DOM Object Type |
Return Value |
|---|---|
|
PBDOM_DOCTYPE |
"#document" |
|
PBDOM_ELEMENT |
The local tag name of the element, without any namespace prefixes. For example, if the element is: <abc>Value</abc>, then the string returned from GetName is "abc". Also, if the tag name of the element contains a namespace prefix, the prefix is not included in the returned string. For example, if the element is: <MyMusic:CD xmlns:MyMusic=, then the string returned from GetName is "CD". "http://www.MyMusicDiscs.com"/> |
|
PBDOM_ATTRIBUTE |
The local name of the attribute itself, without a namespace. For example, if the element with the attribute is: <abc ATTRIBUTE_1="My Attribute">, then GetName returns "ATTRIBUTE_1". If the name of the attribute contains a namespace prefix, then the prefix is not included in the returned string. For example, if the element with an attribute is: <MyMusic:CD xmlns:MyMusic=, then GetName returns the string "Type". "http://www.MyMusicDiscs.com" MyMusic:Type="Jazz"/> |
|
PBDOM_CDATA |
"#cdata-section" |
|
PBDOM_COMMENT |
"#comment" |
|
PBDOM_DOCTYPE |
The name that was given to the doctype object itself. For example, if the DOCTYPE declaration is: <!DOCTYPE d_grid_object >, then GetName returns "d_grid_object". |
|
PBDOM_PROCESSINGINSTRUCTION |
The name that was given to the processing instruction itself. For example, if the processing instruction definition is: <?works document="hello.doc" data="hello.wks" ?>, then GetName returns "works". |
|
PBDOM_TEXT |
"#text" |
Syntax
pbdom_object_name.GetName()
Return value
The following table lists the return values, based on the type of DOM Object contained within the PBDOM_OBJECT:
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
A PBDOM_OBJECT cannot be instantiated directly.
See also
Description
Returns a long integer code that indicates the class of this PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClass()
Return value
Long.
A code that indicates the class of the current PBDOM_OBJECT.
Usage
This method returns the following possible values:
|
Class |
Long integer value |
|---|---|
|
UNKNOWN (indicates an error) |
0 |
|
PBDOM_OBJECT (the base class) |
1 |
|
PBDOM_DOCUMENT |
2 |
|
PBDOM_ELEMENT |
3 |
|
PBDOM_DOCTYPE |
4 |
|
PBDOM_ATTRIBUTE |
5 |
|
PBDOM_CHARACTERDATA |
6 |
|
PBDOM_TEXT |
7 |
|
PBDOM_CDATA |
8 |
|
PBDOM_COMMENT |
9 |
|
PBDOM_PROCESSINGINSTRUCTION |
10 |
|
PBDOM_ENTITYREFERENCE |
11 |
See also
Description
Returns a string form of the class of the PBDOM_OBJECT.
Syntax
pbdom_object_name.GetObjectClassString()
Return value
String.
A string that indicates the class of the current PBDOM_OBJECT.
Usage
This method returns the following possible values:
|
Class |
String returned |
|---|---|
|
PBDOM_OBJECT |
pbdom_object |
|
PBDOM_DOCUMENT |
pbdom_document |
|
PBDOM_ELEMENT |
pbdom_element |
|
PBDOM_ENTITYREFERENCE |
pbdom_entityreference |
|
PBDOM_DOCTYPE |
pbdom_doctype |
|
PBDOM_ATTRIBUTE |
pbdom_attribute |
|
PBDOM_CHARACTERDATA |
pbdom_characterdata |
|
PBDOM_TEXT |
pbdom_text |
|
PBDOM_CDATA |
pbdom_cdata |
|
PBDOM_COMMENT |
pbdom_comment |
|
PBDOM_PROCESSINGINSTRUCTION |
pbdom_processinginstruction |
See also
Description
Returns the owning PBDOM_DOCUMENT of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetOwnerDocumentObject()
Return value
PBDOM_DOCUMENT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
The owning PBDOM_DOCUMENT of the current PBDOM_OBJECT is null if PBDOM_OBJECT is not owned by any PBDOM_DOCUMENT, or if the current PBDOM_OBJECT is itself a PBDOM_DOCUMENT object.
See also
Description
Returns the parent PBDOM_OBJECT of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetParentObject()
Return value
PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Examples
Using the GetRootElement method, the root element of a PBDOM_DOCUMENT called pbdom_doc is returned into a PBDOM_OBJECT called pbdom_obj. The GetParentObject method returns the parent of the root element, which is the PBDOM_DOCUMENT itself, and stores it in pbdom_parent_obj.
The GetObjectClassString method returns the class name of pbdom_parent_obj as a string that is displayed in a message box:
pbdom_document pbdom_doc
pbdom_object pbdom_obj
pbdom_object pbdom_parent_obj
string strClassName
// code omitted
…
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_obj = pbdom_doc.GetRootElement()
pbdom_parent_obj = pbdom_obj.GetParentObject()
strClassName = pbdom_parent_obj.GetObjectClassString()
MessageBox ("Parent Class Name", strClassName)Usage
If the PBDOM_OBJECT has no parent, null is returned.
See also
Description
Obtains the text data that is contained within the current PBDOM_OBJECT.
Syntax
pbdom_object_name.GetText()
Return value
String.
The following table lists the return values, based on the type of DOM Object contained within a PBDOM_OBJECT:
|
DOM Object Type |
Return Value |
|---|---|
|
PBDOM_ELEMENT |
The concatenation of the text values of all the TEXT nodes contained within the PBDOM_ELEMENT. If the PBDOM_ELEMENT definition is <abc>Root Element Data<data>ABC Data </data> now with extra info </abc>, then GetText returns "Root Element Data now with extra info ". Extra Spaces There are extra spaces between the word "Data" and "now" and again after the word "info". They are there because they originally exist in the text. If the PBDOM_ELEMENT definition is: <abc>Root Element Data</abc>, then GetText returns "Root Element Data". |
|
PBDOM_ATTRIBUTE |
The text data contained within the PBDOM_ATTRIBUTE object. If the element with an attribute is <abc ATTRIBUTE_1="My Attribute">, then GetText returns "My Attribute". |
|
PBDOM_TEXT |
The text data contained within the PBDOM_TEXT object itself. For example, suppose there is the following element: <abc>MY TEXT</abc> If there is a PBDOM_TEXT object to represent the text node "MY TEXT", then calling GetText on the PBDOM_TEXT returns the string "MY TEXT" |
|
PBDOM_CDATA |
The string data that is contained within the CDATA section itself. For example, suppose there is the following CDATA: <![CDATA[ They're saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetText on it returns the following string: They're saying "x < y" & that "z > y" so I guess that means that z > x |
|
PBDOM_COMMENT |
The string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT: <!--This is some comment. --> If there is a PBDOM_COMMENT to represent the above COMMENT, then calling GetText on it returns the following string: This is some comment. |
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain text nodes, CDATA sections, or basic text. These include:
-
PBDOM_ELEMENT
-
PBDOM_ATTRIBUTE
-
PBDOM_TEXT
-
PBDOM_CDATA
-
PBDOM_COMMENT
The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT objects are special cases that cause the GetText method to return the text data that is intrinsically contained within the objects. A PBDOM_TEXT object is basically a DOM text node and therefore does not hold any child text nodes. A PBDOM_CDATA object represents a DOM CDATA object, and therefore does not hold any child DOM nodes. The same rule applies to a PBDOM_COMMENT object.
See also
Description
Gets the text data that is contained in the current PBDOM_OBJECT with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
Syntax
pbdom_object_name.GetTextNormalize()
Return value
String.
The normalized text content of the current PBDOM_OBJECT, or an empty string if there is no text content.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain text nodes or CDATA sections, or of a type that intrinsically contains basic text. These types are:
-
PBDOM_ELEMENT
-
PBDOM_ATTRIBUTE
-
PBDOM_TEXT
-
PBDOM_CDATA
-
PBDOM_COMMENT
The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT classes are special cases that cause the GetTextNormalize method to return the intrinsic text data contained within their instances. A PBDOM_TEXT object represents a DOM text node, therefore it does not hold any child DOM Nodes. PBDOM_CDATA object is a representation of a DOM CDATA object and does not hold any child DOM Nodes. Nor does PBDOM_COMMENT contain any child DOM Nodes.
The following table lists the return values based on the type of actual DOM Object contained within PBDOM_OBJECT:
|
DOM Object Type |
Return Value |
|---|---|
|
PBDOM_ELEMENT |
The normalized text of the concatenation of the text values of all the TEXT Nodes and CDATA Sections contained within the PBDOM_ELEMENT. Suppose there is a PBDOM_ELEMENT defined as follows: <abc> Root Element Data <data>ABC Data </data> now with extra info </abc> GetTextNormalize returns Root Element Data now with extra info. Suppose there is a PBDOM_ELEMENT defined as follows: <abc> Root Element Data </abc> GetTextNormalize returns Root Element Data. Suppose there is a PBDOM_ELEMENT defined as follows: <abc> Root Element Data <![CDATA [ with some cdata text]]></abc> GetTextNormalize returns "Root Element Data with some cdata text". |
|
PBDOM_ATTRIBUTE |
The normalized text data contained within the PBDOM_ATTRIBUTE object. Suppose there is an element with an attribute as follows: <abc ATTRIBUTE_1=" My Attribute "> GetTextNormalize returns My Attribute. |
|
PBDOM_TEXT |
The normalized text data contained within the PBDOM_TEXT object itself. For example, suppose there is the following element: <abc> MY TEXT </abc> If there is a PBDOM_TEXT object to represent the text node "MY TEXT", then calling GetTextNormalize on the PBDOM_TEXT returns the string MY TEXT. |
|
PBDOM_CDATA |
The normalized string data that is contained within the CDATA section itself. For example, suppose there is the following CDATA: <![CDATA[ They're saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextNormalize on it returns the string: They're saying " x < y " & that "z > y" so I guess that means that z > x Note that the initial spaces before "They're" and the trailing space after the last "x" have been removed. Additionally, the spaces between the word "guess" and "that" have been reduced to just one space. |
|
PBDOM_COMMENT |
The normalized string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT: <!-- Comment Here !--> Calling GetTextNormalize on the COMMENT returns the string Comment Here ! |
See also
Description
Gets the text data that is contained in the current PBDOM_OBJECT with all surrounding whitespace characters removed.
Syntax
pbdom_object_name.GetTextTrim()
Return value
String.
The trimmed text content of the current PBDOM_OBJECT, or an empty string if there is no text content or only whitespace characters.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
Usage
This method returns meaningful data only if the PBDOM_OBJECT is of a type that can contain TEXT NODEs or CDATA Sections, or of a type that intrinsically contains basic text. These types are:
-
PBDOM_ELEMENT
-
PBDOM_ATTRIBUTE
-
PBDOM_TEXT
-
PBDOM_CDATA
-
PBDOM_COMMENT
The PBDOM_TEXT, PBDOM_CDATA, and PBDOM_COMMENT classes are special cases that cause the GetTextTrim method to return the intrinsic text data contained within their instances. A PBDOM_TEXT object represents a DOM text node, so it does not hold any child DOM Nodes. PBDOM_CDATA object is a representation of a DOM CDATA object and does not hold any child DOM Nodes, nor does PBDOM_COMMENT contain any child DOM Nodes.
The following table lists the return values based on the type of actual DOM Object contained within PBDOM_OBJECT:
|
DOM Object Type |
Return Value |
|---|---|
|
PBDOM_ELEMENT |
The trimmed concatenation of the text values of all the TEXT Nodes and CDATA Sections contained within the PBDOM_ELEMENT. Surrounding whitespace characters are removed. Suppose there is a PBDOM_ELEMENT defined as follows: <abc> Root Element Data<data>ABC Data </data> now with extra info </abc> GetTextTrim returns Root Element Data now with extra info. Suppose there is a PBDOM_ELEMENT defined as follows: <abc> Root Element Data </abc> GetTextTrim returns Root Element Data. Suppose there is a PBDOM_ELEMENT defined as follows: <abc>Root Element Data <![CDATA[ with some cdata text]]></abc> GetTextTrim returns Root Element Data with some cdata text. |
|
PBDOM_ATTRIBUTE |
The trimmed text data contained within the PBDOM_ATTRIBUTE object with surrounding whitespace characters removed. Suppose there is an element with an attribute as follows: <abc ATTRIBUTE_1="My Attribute "> GetTextTrim returns: My Attribute Note, however, that the spaces between "My" and "Attribute" are still present. |
|
PBDOM_TEXT |
The trimmed text data contained within the PBDOM_TEXT object itself with surrounding whitespace characters removed. For example, suppose there is the following element: <abc> MY TEXT </abc> If there is a PBDOM_TEXT object to represent the text node "MY TEXT ", then calling GetTextTrim on the PBDOM_TEXT returns the string MY TEXT. |
|
PBDOM_CDATA |
The trimmed string data that is contained within the CDATA section itself with surrounding whitespace characters removed. For example, suppose there is the following CDATA: <![CDATA[ They're saying "x < y" & that "z > y" so I guess that means that z > x ]]> If there is a PBDOM_CDATA to represent the above CDATA section, then calling GetTextTrim on it returns the string: They're saying " x < y " & that "z > y" so I guess that means that z > x Note that the initial spaces before "They're" and the trailing space after the last "x" have been removed. |
|
PBDOM_COMMENT |
The trimmed string data that is contained within the COMMENT itself. For example, suppose there is the following COMMENT: <!-- Comment Here ! --> Note the spaces before the word "Comment" and after the exclamation mark "!". Calling GetTextTrim on the COMMENT returns the string Comment Here ! |
See also
Description
Determines whether the PBDOM_OBJECT has any child objects.
Syntax
pbdom_object_name.HasChildren()
Return value
Boolean.
Returns true if the current PBDOM_OBJECT has at least one child PBDOM_OBJECT, and false if it has none.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Examples
In the following example, a PBDOM_DOCUMENT is created from a simple XML string. The root element abc has a child text node that encapsulates the text "abc data". Calling HasChildren on the root element returns true. The message box displays Has Children. If the method returns false, the message box displays Has No Children
PBDOM_Builder pbdombuilder_new
pbdom_document pbdom_doc
pbdom_object pbdom_root_element
string strXML = "<abc>abc data</abc>"
pbdombuilder_new = Create PBDOM_Builder
pbdom_doc = pbdombuilder_new.BuildFromString (strXML)
pbdom_root_element = pbdom_doc.GetRootElement()
if (pbdom_root_element.HasChildren()) then
MessageBox ("pbdom_root_element", "Has Children")
else
MessageBox ("pbdom_root_element", "Has No Children")
end if
Destroy pbdombuilder_newUsage
True is returned if the PBDOM_OBJECT has at least one child, and false if there are no children.
Description
Inserts a new PBDOM_OBJECT into the current PBDOM_OBJECT.
Syntax
pbdom_object_name.InsertContent(pbdom_object_new, pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_new |
The referenced name of a PBDOM_OBJECT you want to insert |
|
pbdom_object_ref |
The name of the PBDOM_OBJECT in front of which you want to insert the new PBDOM_OBJECT |
Return value
PBDOM_OBJECT. The return value is the newly modified PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object or the new PBDOM_OBJECT or the reference PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- One of the input arguments is invalid. This can happen if the input argument has not been initialized properly or is a null object reference.
Usage
When a new PBDOM_OBJECT is inserted into the current PBDOM_OBJECT, the new PBDOM_OBJECT becomes a child node of the current PBDOM_OBJECT. Also, the new PBDOM_OBJECT is to be positioned specifically before another PBDOM_OBJECT, designated using the second parameter.
If the second PBDOM_OBJECT is specified as null, then the new PBDOM_OBJECT is to be inserted at the end of the list of children of the current PBDOM_OBJECT.
Derived Classes
Methods of classes that derive from the PBDOM_OBJECT class return trivial results when the derived classes can have no child objects and when the methods concern manipulation of child-node content.
See also
Description
Determines whether the current PBDOM_OBJECT is the ancestor of another PBDOM_OBJECT.
Syntax
pbdom_object_name.IsAncestorObjectOf(pbdom_object_ret)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_ref |
The PBDOM_OBJECT to check against |
Return value
Boolean.
Returns true if the current PBDOM_OBJECT is the ancestor of the referenced PBDOM_OBJECT, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- The input PBDOM_OBJECT is invalid. This can happen if it has not been initialized properly or it is a null object reference.
Examples
The following code fragment uses the IsAncestorObjectOf method and creates a structured document. In the fragment, pbdom_elem_1 represents the pbdom_elem_1 element. Because it is an ancestor of pbdom_elem_3, which represents the pbdom_elem_ element, the call to IsAncestorObjectOf returns true.
PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_2
PBDOM_ELEMENT pbdom_elem_3
PBDOM_ELEMENT pbdom_elem_root
PBDOM_DOCUMENT pbdom_doc1
pbdom_doc1 = Create PBDOM_DOCUMENT
pbdom_elem_1 = Create PBDOM_ELEMENT
pbdom_elem_2 = Create PBDOM_ELEMENT
pbdom_elem_3 = Create PBDOM_ELEMENT
pbdom_elem_1.SetName("pbdom_elem_1")
pbdom_elem_2.SetName("pbdom_elem_2")
pbdom_elem_3.SetName("pbdom_elem_3")
pbdom_elem_1.AddContent(pbdom_elem_2)
pbdom_elem_2.AddContent(pbdom_elem_3)
pbdom_doc1.NewDocument("", "", &
"Root_Element_From_Doc_1" , "", "")
pbdom_elem_root = pbdom_doc1.GetRootElement()
pbdom_elem_root.AddContent(pbdom_elem_1)
IF (pbdom_elem_1.IsAncestorObjectOf(pbdom_elem_3)) THEN
MessageBox ("Ancestry", &
"pbdom_elem_1 Is The Ancestor Of pbdom_elem_3")
ELSE
MessageBox ("Ancestry", &
"pbdom_elem_1 Is NOT The Ancestor Of pbdom_elem_3")
END IF
destroy pbdom_elem_1
destroy pbdom_elem_2
destroy pbdom_elem_3
destroy pbdom_elem_root
destroy pbdom_doc1
The preceding code fragment creates the following document:
<!DOCTYPE Root_Element_From_Doc_1> <Root_Element_From_Doc_1> <pbdom_elem_1> <pbdom_elem_2> <pbdom_elem_3 /> </pbdom_elem_2> </pbdom_elem_1> </Root_Element_From_Doc_1>
Usage
The IsAncestorObjectOf method determines whether the current PBDOM_OBJECT is the ancestor of another PBDOM_OBJECT.
Description
Removes a child PBDOM_OBJECT from the current PBDOM_OBJECT.
Syntax
pbdom_object_name.RemoveContent(pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_ref |
The PBDOM_OBJECT to remove |
Return value
Boolean.
Returns true if the content was removed, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- The input PBDOM_OBJECT to be removed is invalid. This can happen if this object has not been initialized properly or is a null object reference.
Usage
When a new PBDOM_OBJECT is removed from the current one, all children under the removed PBDOM_OBJECT are also removed.
See also
Description
Sets the entire content of the PBDOM_OBJECT.
Syntax
pbdom_object_name.SetContent(pbdon_objectpbdom_object_array)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM object |
|
pbdom_object_array |
An array of PBDOM_OBJECT objects to be set as the contents of the PBDOM_OBJECT |
Return value
PBDOM_OBJECT. Returns the newly modified PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
Usage
The supplied array contains PBDOM_OBJECT objects that are legal for the particular derived PBDOM_OBJECT that is associated with this PBDOM_OBJECT.
For example, a PBDOM_DOCUMENT accepts only an array that contains PBDOM_ELEMENT, PBDOM_COMMENT, PBDOM_DOCTYPE, or PBDOM_PROCESSINGINSTRUCTION objects. In addition, the array can contain only one PBDOM_ELEMENT object that it sets as its root element, and only one PBDOM_DOCTYPE object that is set as its DOCTYPE.
If illegal objects are included in the array, exceptions (specific to the particular derived PBDOM_OBJECT) are thrown. For more details, please refer to the SetContent method of the objects derived from PBDOM_OBJECT.
In the event of an exception, the original contents of this PBDOM_OBJECT are unchanged, and the PBDOM_OBJECT objects contained in the supplied array are unaltered.
See also
Description
Sets the name of the PBDOM_OBJECT.
Syntax
pbdom_object_name.SetName(stringstrName)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
strName |
The new name you want to set for PBDOM_OBJECT |
Return value
Boolean.
Returns true if the name of the PBDOM_OBJECT was changed, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- Input name string is invalid. This can happen if the string has been specifically set to null.
EXCEPTION_MEMORY_ALLOCATION_FAILURE -- Insufficient memory was encountered while executing this method.
EXCEPTION_INVALID_NAME -- The input name string does not conform to the W3C standards for XML names.
Usage
This name refers to the name of the particular derived PBDOM_OBJECT to which this PBDOM_OBJECT refers. Certain types of PBDOM_OBJECT do not have any name associated with them. See the description of GetName.
For example, PBDOM_DOCUMENT does not have any name, so calling the SetName method returns false.
See also
Description
Sets the referenced PBDOM_OBJECT as the parent of the current PBDOM_OBJECT.
Syntax
pbdom_object_name.SetParentObject(pbdom_object pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_object_name |
The name of the PBDOM_OBJECT |
|
pbdom_object_ref |
The PBDOM_OBJECT to be set as the parent of the current PBDOM_OBJECT |
Return value
PBDOM_OBJECT. The current PBDOM_OBJECT is appended as a child node of the referenced parent.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- This PBDOM_OBJECT object or the input PBDOM_OBJECT is not associated with a derived PBDOM_OBJECT class object.
EXCEPTION_INVALID_ARGUMENT -- The input PBDOM_OBJECT is invalid. This can happen if it has not been initialized properly, or if it is a null object reference.
EXCEPTION_PBDOM_OBJECT_ALREADY_HAS_PARENT -- The current PBDOM_OBJECT already has a parent.
EXCEPTION_INAPPROPRIATE_USE_OF_PBDOM_OBJECT -- If the input PBDOM_OBJECT is of a class that cannot have a legal parent-child relationship with this PBDOM_OBJECT.
Examples
In the following code example, a PBDOM_ELEMENT object is created and called pbdom_elem_1. Its parent is set to be the root element of the PBDOM_DOCUMENT called pbdom_doc. Once this is done, pbdom_elem_1 is immediately transferred to the pbdom_doc document and pbdom_elem_1 is immediately appended as a child node of the root element of pbdom_doc.
The following method call returns the string "pbdom_element", because the root element is a PBDOM_ELEMENT:
pbdom_elem_1.GetParentObject().GetObjectClassString()
The following method call returns the string "Root_Element", which is the name of the root element:
pbdom_elem_1.GetParentObject().GetName()
Here is the complete example:
PBDOM_ELEMENT pbdom_elem_1
PBDOM_ELEMENT pbdom_elem_root
PBDOM_DOCUMENT pbdom_doc1
pbdom_doc1 = Create PBDOM_DOCUMENT
pbdom_elem_1 = Create PBDOM_ELEMENT
pbdom_elem_1.SetName ("pbdom_elem_1")
pbdom_doc1.NewDocument ("", "", "Root_Element", "", "")
pbdom_elem_root = pbdom_doc1.GetRootElement()
pbdom_elem_1.SetParentObject(pbdom_elem_root)
MessageBox ("Parent Class", &
pbdom_elem_1.GetParentObject(). &
GetObjectClassString())
MessageBox ("Parent Name", &
pbdom_elem_1.GetParentObject().GetName())
destroy pbdom_elem_1
destroy pbdom_elem_root
destroy pbdom_doc1Usage
The caller is responsible for ensuring that the current PBDOM_OBJECT and the referenced PBDOM_OBJECT can have a legal parent-child relationship. The caller is also responsible for making sure pre-existing parentage is legal.
The PBDOM SetParentObject method differs from the JDOM SetParent method in that JDOM defines a setParent method for several specific classes, including Element, Comment, and CDATA. PBDOM implements the SetParentObject method in the base PBDOM_OBJECT class to allow polymorphism.
See the SetParentObject documentation of derived PBDOM_OBJECT classes for more details on implementation of specific classes.
See also
