PowerBuilder Extension Reference
PBDOM_CHARACTERDATA

Description

Creates and returns a clone of the current PBDOM_CHARACTERDATA.

Syntax

pbdom_chardata_name.Clone(boolean bDeep)

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:

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

The PowerScript code obtains the data element of the root element as a PBDM_ELEMENT and obtains an array of its children. The array has only one item, the PBDOM_TEXT containing the string "data":

PBDOM_BUILDER pbdombuilder_new
PBDOM_DOCUMENT pbdom_doc
PBDOM_ELEMENT pbdom_elem
PBDOM_CHARACTERDATA pbdom_chardata_1
PBDOM_CHARACTERDATA pbdom_chardata_2
PBDOM_CHARACTERDATA pbdom_chardata_3
PBDOM_OBJECT pbdom_obj_array[]
string strXML = "<abc><data>Data</data></abc>"

TRY
   pbdombuilder_new = CREATE PBDOM_BUILDER
   pbdom_doc = pbdombuilder_new.BuildFromString (strXML)

// get the data element, store in pbdom_elem,
// and get an array of its children
   pbdom_elem = pbdom_doc.GetRootElement(). &
      GetChildElement("data")
   pbdom_elem.GetContent(pbdom_obj_array)

This PBDOM_TEXT is assigned into a PBDOM_CHARACTERDATA object, pbdom_chardata_1. Calling GetObjectClassString on pbdom_chardata_1 returns the class name of the actual object contained within it, pbdom_text. Calling GetText on it returns the string Data:

   pbdom_chardata_1 = pbdom_obj_array[1]
   MessageBox ("Class", &
      pbdom_chardata_1.GetObjectClassString())
   MessageBox ("Text", pbdom_chardata_1.GetText())

Calling Clone on pbdom_chardata_1 creates a new PBDOM_CHARACTERDATA object. However, because the actual object referenced by pbdom_chardata_1 is a PBDOM_TEXT, the clone is a PBDOM_TEXT object.

Calling GetObjectClassString and GetText on the clone have the same result as for pbdom_chardata_1. The clone and the original object are separate objects and a call to Equals returns false:

   pbdom_chardata_2 = pbdom_chardata_1.Clone(TRUE)
   MessageBox ("Class", &
      pbdom_chardata_2.GetObjectClassString())
   MessageBox ("Text", pbdom_chardata_2.GetText())
   if (pbdom_chardata_1.Equals(pbdom_chardata_2)) then
     MessageBox ("Equals", &
        "pbdom_chardata_1 equals pbdom_chardata_2")
   else
     MessageBox ("Equals", &
       "pbdom_chardata_1 NOT equals pbdom_chardata_2")
   end if

However, a call to Equals returns true if the object being compared to pbdom_chardata_1 is a reference to pbdom_chardata_1:

   pbdom_chardata_3 = pbdom_chardata_1
   if (pbdom_chardata_1.Equals(pbdom_chardata_3)) then
     MessageBox ("Equals", &
        "pbdom_chardata_1 equals pbdom_chardata_3")
   else
     MessageBox ("Equals", &
        "pbdom_chardata_1 NOT equals pbdom_chardata_3")
   end if

   DESTROY pbdombuilder_new

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

Usage

The Clone method creates a new PBDOM_CHARACTERDATA object which is a duplicate of, and a separate object from, the original. Calling Equals using these two objects returns false.

The clone of a PBDOM_CHARACTERDATA object is always identical to its original whether bDeep is true or false, because a PBDOM_CHARACTERDATA object contains no subtree of child PBDOM_OBJECTs.

A PBDOM_CHARACTERDATA clone has no parent, but it resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_CHARACTERDATA is standalone, the clone is standalone.