PowerBuilder Extension Reference
PBDOM_CHARACTERDATA

Description

The GetParentObject method returns the parent PBDOM_OBJECT of the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.GetParentObject()

Return value

PBDOM_OBJECT.

Throws

EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If this PBDOM_CHARACTERDATA is not a reference to an object derived from PBDOM_CHARACTERDATA.

Examples

This example creates a PBDOM_DOCUMENT based on the following DOM tree and demonstrates how a PBDOM_CHARACTERDATA INSTANCE can be detached from its parent:

<abc>
   <data>Data</data>
</abc>

The PowerScript code obtains the root element, uses it to obtain the child element, and then obtains an array of the child element's own children. This array has a single item, the PBDOM_TEXT object with the text Data. The array can be cast to a PBDOM_CHARACTERDATA object, because it does not contain any objects that are not derived from PBDOM_CHARACTERDATA.

The parent of pbdom_chardata_1 is the data element. The following steps detach it from its parent:

Calling SetContent resets the contents of data, which can cause its original contents (including pbdom_chardata_1) to be removed, depending on what is stored inside pbdom_obj_array. Because pbdom_obj_array contains only the newly created PBDOM_COMMENT, pbdom_chardata_2, data will have only this PBDOM_COMMENT as its child.

pbdom_chardata_1 will have no parent, because it has been silently detached from it. Calling GetParentObject on it will return null:

PBDOM_Builder          pbdombuilder_new
pbdom_document         pbdom_doc
pbdom_document         pbdom_owner_doc
PBDOM_CHARACTERDATA    pbdom_chardata_1
PBDOM_CHARACTERDATA    pbdom_chardata_2
PBDOM_OBJECT           pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"

TRY
 pbdombuilder_new = Create PBDOM_Builder
 pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

 pbdom_doc.GetRootElement(). &
   GetChildElement("data"). &
   GetContent(pbdom_obj_array)

 pbdom_chardata_1 = pbdom_obj_array[1]

 pbdom_chardata_2 = Create PBDOM_COMMENT
 pbdom_chardata_2.SetText ("Some Comments")

 pbdom_obj_array[1] = pbdom_chardata_2

 pbdom_chardata_1.GetParentObject(). &
    SetContent(pbdom_obj_array)

 if (IsValid(pbdom_chardata_1.GetParentObject())) then
    MessageBox ("Has Parent Object", &
      "PBDOMTEXT (~'Data~') has a parent")
 else
    MessageBox ("Has Parent Object", &
      "PBDOMTEXT (~'Data~') has NO parent")
 end if

 pbdom_doc.SaveDocument("c:\pbdom_doc_1.xml")

 Destroy pbdombuilder_new
 Destroy pbdom_chardata_2

CATCH (PBDOM_Exception except)
 MessageBox ("Exception Occurred", except.Text)
END TRY

When the resulting PBDOM_DOCUMENT is saved to a file, it looks like this:

<abc>
   <data>
      <!-- Some Comments -->
   </data>
</abc>

Usage

The parent is also an object derived from PBDOM_CHARACTERDATA. If the PBDOM_OBJECT has no parent, null is returned.

See also

SetParentObject