InsertElement Method

Summary

Inserts a new element in the Data Set.

Syntax

Objective-C

C++/CLI

Java

public DicomElement InsertElement( 
   DicomElement neighbor, 
   bool child, 
   long tag, 
   DicomVRType vr, 
   bool sequence, 
   int index 
)

- (nullable LTDicomElement *)insertElement:(nullable LTDicomElement *)neighbor child:(BOOL)child tag:(LTDicomTagCode)tag VR:(LTDicomVRType)vr sequence:(BOOL)sequence index:(NSInteger)index error:(NSError **)error;

public DicomElement insertElement(DicomElement neighbor, boolean child, long tag, DicomVrType vr, boolean sequence, int index )

public: 
DicomElement^ InsertElement(  
   DicomElement^ neighbor, 
   bool child, 
   int64 tag, 
   DicomVRType vr, 
   bool sequence, 
   int index 
)

Parameters

neighbor
An item in the Data Set. The inserted item will be inserted as a neighbor to this item, or as a child, depending on the value of child.

child
true to insert the new item as the last child of neighbor; false to insert the new item as the last sibling of neighbor.

tag
Tag value for the inserted element. For a list of default values, refer to Data Element Tag Values.

vr
Value representation code that indicates the type of value stored in the data element.

sequence
true if the new item is a sequence; otherwise, false.

index
The index at which the data element should be inserted in a sequence. The index is zero-based, so if you want to insert a data element as the first item in the sequence, set this to 0. The value -1 indicates to add the data element to the end of the sequence.

A sequence may consist of one or more items. This parameter lets you insert a data element as any item within the sequence, not just at the end. In addition, it lets you insert multiple data elements within a sequence.

If neighbor points to the parent of a sequence and child is true, the index will pertain to the children of neighbor. If neighbor points to a member of a sequence and child is false, the index pertains to the siblings of neighbor.

Return Value

The newly inserted item.

Remarks

The illustrations below show how items are added to the Data Set (internally maintained as a tree), based on the value of child. For the sake of these illustrations, the order of siblings is top to bottom. Therefore, since added items become the last sibling or the last child, these are drawn at the bottom of the appropriate group of items.

In this illustration, neighbor points to Item 1 and child is false. The new item is added as the last sibling of Item 1.

In this illustration, neighbor points to Item 1 and child is true. The new item is added as the last child of Item 1.

Example

using Leadtools; 
using Leadtools.Dicom; 
 
 
public void LoadEnumerateSample() 
{ 
   string dicomFileName = Path.Combine(LEAD_VARS.ImagesDir, "DICOM", "image3.dcm"); 
   //Make sure to initialize the DICOM engine, this needs to be done only once  
   //In the whole application 
   DicomEngine.Startup(); 
   using (DicomDataSet ds = new DicomDataSet()) 
   { 
      //Load DICOM File 
      ds.Load(dicomFileName, DicomDataSetLoadFlags.None); 
      //Insert patient name element, if it doesn't already exist 
      DicomElement element = ds.FindFirstElement(null, DicomTag.PatientName, false); 
      if (element == null) 
      { 
         element = ds.InsertElement(null, false, DicomTag.PatientName, DicomVRType.PN, false, 0); 
      } 
      //The dataset should include the patient name element or an error occurred 
      element = ds.FindLastElement(null, DicomTag.PatientName, false); 
      Debug.Assert(element != null); 
      //There can be only one patient element in the root level 
      element = ds.FindPreviousElement(null, false); 
      Debug.Assert(element == null); 
      element = ds.FindNextElement(null, false); 
      Debug.Assert(element == null); 
 
      element = ds.FindFirstElement(null, DicomTag.PatientName, false); 
      //Since the patient name element is in the root level, 
      //GetRootElement will return the same element. 
      DicomElement element1 = ds.GetRootElement(element); 
      Debug.Assert((element1.Tag == element.Tag), "GetRootElement should return same element"); 
 
      //Since the patient name element has no parent then GetParentElement will return null 
      element1 = ds.GetParentElement(element); 
      Debug.Assert(element1 == null, "GetParentElement should return null"); 
 
      //Since the patient name element has no children then GetChildElement will return null 
      element1 = ds.GetChildElement(element, false); 
      Debug.Assert(element1 == null, "GetChildElement should return null"); 
 
      element1 = ds.GetFirstElement(element, false, false); 
      Debug.Assert(element1 != null, "GetFirstElement Can't return null in this case"); 
 
      element1 = ds.GetLastElement(element, false, false); 
      Debug.Assert(element1 != null, "GetLastElement Can't return null in this case"); 
 
      element1 = ds.GetPreviousElement(element, false, true); 
      DicomElement element2 = ds.GetNextElement(element, false, true); 
 
      Debug.Assert(ds.GetElementLevel(element) == 0); 
 
      Debug.Assert(ds.ExistsElement(element)); 
      Debug.Assert(ds.IsVolatileElement(element) == false); 
 
      //Patient Name is not the only element in this level 
      Debug.Assert((element1 != null) && (element2 != null)); 
      //Delete the patient name element 
      ds.DeleteElement(element); 
   } 
   DicomEngine.Shutdown(); 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\LEADTOOLS23\Resources\Images"; 
}