PowerBuilder Extension Reference
PBDOM_OBJECT

Description

Sets the referenced PBDOM_OBJECT as the parent of the current PBDOM_OBJECT.

Syntax

pbdom_object_name.SetParentObject(pbdom_object pbdom_object_ref)

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_doc1

Usage

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

GetOwnerDocumentObject

GetParentObject