DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Private Member Functions | Private Attributes | List of all members
DVPSGraphicAnnotation_PList Class Reference

the list of graphic annotations contained in a presentation state (internal use only). More...

## Public Member Functions
| DVPSGraphicAnnotation_PList ()
| default constructor
| DVPSGraphicAnnotation_PList (const DVPSGraphicAnnotation_PList &copy)
| copy constructor
DVPSGraphicAnnotation_PList * | clone ()
| clone method. More...
virtual | ~DVPSGraphicAnnotation_PList ()
| destructor
OFCondition | read (DcmItem &dset)
| reads a list of graphic annotations from a DICOM dataset. More...
OFCondition | write (DcmItem &dset)
| writes the list of graphic annotations managed by this object to a DICOM dataset. More...
void | clear ()
| reset the object to initial state. More...
void | renameLayer (const char *oldName, const char *newName)
| renames the graphic annotation layer name in all activations with a matching old graphic annotation layer name. More...
void | removeLayer (const char *name)
| deletes all graphic annotation layers belonging to the given graphic annotation layer name. More...
void | cleanupLayers ()
| deletes all graphic annotation sequence items containing no text and no graphic object. More...
OFBool | usesLayerName (const char *name)
| checks if the given layer name is used for any of the graphic annotation layers managed by this object. More...
size_t | getNumberOfTextObjects (const char *layer, const char *instanceUID, unsigned long frame)
| returns the number of text objects for the given graphic layer that apply to the given image and frame. More...
DVPSTextObject * | getTextObject (const char *layer, const char *instanceUID, unsigned long frame, size_t idx)
| gets the text object (applicable to the current image and frame) with the given index on the given layer. More...
DVPSTextObject * | addTextObject (const char *layer, const char *sopclassUID, const char *instanceUID, unsigned long frame, DVPSObjectApplicability applicability, DVPSTextObject *text=NULL)
| creates a new text object on the given layer. More...
OFCondition | removeTextObject (const char *layer, const char *instanceUID, unsigned long frame, size_t idx)
| deletes the text object (applicable to the current image and frame) with the given index on the given layer. More...
OFCondition | moveTextObject (const char *old_layer, const char *sopclassUID, const char *instanceUID, unsigned long frame, size_t idx, DVPSObjectApplicability applicability, const char *new_layer)
| moves the text object (applicable to the current image and frame) with the given index on the given layer to a different layer. More...
size_t | getNumberOfGraphicObjects (const char *layer, const char *instanceUID, unsigned long frame)
| returns the number of graphic objects for the given graphic layer. More...
DVPSGraphicObject * | getGraphicObject (const char *layer, const char *instanceUID, unsigned long frame, size_t idx)
| gets the graphic object with the given index on the given layer. More...
DVPSGraphicObject * | addGraphicObject (const char *layer, const char *sopclassUID, const char *instanceUID, unsigned long frame, DVPSObjectApplicability applicability, DVPSGraphicObject *graphic=NULL)
| creates a new graphic object on the given layer. More...
OFCondition | removeGraphicObject (const char *layer, const char *instanceUID, unsigned long frame, size_t idx)
| deletes the graphic object with the given index on the given layer. More...
OFCondition | moveGraphicObject (const char *old_layer, const char *sopclassUID, const char *instanceUID, unsigned long frame, size_t idx, DVPSObjectApplicability applicability, const char *new_layer)
| moves the graphic object with the given index on the given layer to a different layer. More...

## Private Member Functions
DVPSGraphicAnnotation_PList & | operator= (const DVPSGraphicAnnotation_PList &)
| private undefined assignment operator

## Private Attributes
OFList< DVPSGraphicAnnotation * > | list_
| the list maintained by this object

## Detailed Description

the list of graphic annotations contained in a presentation state (internal use only).

This class manages the data structures comprising the complete Graphic Annotation Sequence in a Presentation State object.

## Member Function Documentation

## ◆ addGraphicObject()

DVPSGraphicObject* DVPSGraphicAnnotation_PList::addGraphicObject | ( | const char * | layer,
|  | const char * | sopclassUID,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | DVPSObjectApplicability | applicability,
|  | DVPSGraphicObject * | graphic = `NULL`
| ) |  |

creates a new graphic object on the given layer.

Returns a pointer to the new graphic object. If the graphic layer does not exist or if the creation of the graphic object fails, NULL is returned.

Parameters

  layer | name of the graphic layer
  sopclassUID | SOP class UID of the current image
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  applicability | applicability of the new text object
  graphic | the graphic object to be inserted. If NULL, a new graphic object is created. If a pointer to an object is passed in this parameter, it gets owned by this graphic annotation object and will be deleted upon destruction of the annotation or if this method fails (returns NULL).

Returns
  a pointer to the new graphic object

## ◆ addTextObject()

DVPSTextObject* DVPSGraphicAnnotation_PList::addTextObject | ( | const char * | layer,
|  | const char * | sopclassUID,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | DVPSObjectApplicability | applicability,
|  | DVPSTextObject * | text = `NULL`
| ) |  |

creates a new text object on the given layer.

Returns a pointer to the new text object. If no graphic layer with appropriate applicability exists, it is created. If the creation of the layer or text object fails, NULL is returned.

Parameters

  layer | name of the graphic layer
  sopclassUID | SOP class UID of the current image
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  applicability | applicability of the new text object
  text | the text object to be inserted. If NULL, a new text object is created. If a pointer to an object is passed in this parameter, it gets owned by this graphic annotation object and will be deleted upon destruction of the annotation or if this method fails (returns NULL).

Returns
  a pointer to the new text object

## ◆ cleanupLayers()

void DVPSGraphicAnnotation_PList::cleanupLayers | ( |  | ) |

deletes all graphic annotation sequence items containing no text and no graphic object.

Called before writing a presentation state.

## ◆ clear()

void DVPSGraphicAnnotation_PList::clear | ( |  | ) |

reset the object to initial state.

After this call, the object is in the same state as after creation with the default constructor.

## ◆ clone()

DVPSGraphicAnnotation_PList* DVPSGraphicAnnotation_PList::clone | ( |  | ) |
| inline

clone method.

Returns
  a pointer to a new DVPSGraphicAnnotation_PList object containing a deep copy of this object.

## ◆ getGraphicObject()

DVPSGraphicObject* DVPSGraphicAnnotation_PList::getGraphicObject | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx
| ) |  |

gets the graphic object with the given index on the given layer.

If the graphic object or the graphic layer does not exist, NULL is returned.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)

Returns
  a pointer to the graphic object

## ◆ getNumberOfGraphicObjects()

size_t DVPSGraphicAnnotation_PList::getNumberOfGraphicObjects | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame
| ) |  |

returns the number of graphic objects for the given graphic layer.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame

Returns
  number of graphic objects

## ◆ getNumberOfTextObjects()

size_t DVPSGraphicAnnotation_PList::getNumberOfTextObjects | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame
| ) |  |

returns the number of text objects for the given graphic layer that apply to the given image and frame.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame

Returns
  number of text objects

## ◆ getTextObject()

DVPSTextObject* DVPSGraphicAnnotation_PList::getTextObject | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx
| ) |  |

gets the text object (applicable to the current image and frame) with the given index on the given layer.

If the text object or the graphic layer does not exist, NULL is returned.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the text object, must be < getNumberOfTextObjects(layer)

Returns
  a pointer to the text object

## ◆ moveGraphicObject()

OFCondition DVPSGraphicAnnotation_PList::moveGraphicObject | ( | const char * | old_layer,
|  | const char * | sopclassUID,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx,
|  | DVPSObjectApplicability | applicability,
|  | const char * | new_layer
| ) |  |

moves the graphic object with the given index on the given layer to a different layer.

Parameters

  old_layer | name of the graphic layer on which the graphic object is
  sopclassUID | SOP class UID of the current image
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)
  applicability | new applicability of the graphic object
  new_layer | name of the graphic layer to which the graphic object is moved

Returns
  EC_Normal upon success, an error code otherwise

## ◆ moveTextObject()

OFCondition DVPSGraphicAnnotation_PList::moveTextObject | ( | const char * | old_layer,
|  | const char * | sopclassUID,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx,
|  | DVPSObjectApplicability | applicability,
|  | const char * | new_layer
| ) |  |

moves the text object (applicable to the current image and frame) with the given index on the given layer to a different layer.

Parameters

  old_layer | name of the graphic layer on which the text object is
  sopclassUID | SOP class UID of the current image
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the text object, must be < getNumberOfTextObjects(layer)
  applicability | new applicability of the text object
  new_layer | name of the graphic layer to which the text object is moved

Returns
  EC_Normal upon success, an error code otherwise

## ◆ read()

OFCondition DVPSGraphicAnnotation_PList::read | ( | DcmItem & | dset | ) |

reads a list of graphic annotations from a DICOM dataset.

The DICOM elements of the Graphic Annotation Sequence are copied from the dataset to this object. The completeness of the item (presence of all required elements, value multiplicity) is checked. If this method returns an error code, the object is in undefined state afterwards.

Parameters

  dset | the dataset from which the GraphicAnnotationSequence is to be read

Returns
  EC_Normal if successful, an error code otherwise.

## ◆ removeGraphicObject()

OFCondition DVPSGraphicAnnotation_PList::removeGraphicObject | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx
| ) |  |

deletes the graphic object with the given index on the given layer.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the graphic object, must be < getNumberOfGraphicObjects(layer)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ removeLayer()

void DVPSGraphicAnnotation_PList::removeLayer | ( | const char * | name | ) |

deletes all graphic annotation layers belonging to the given graphic annotation layer name.

Parameters

  name | name of the graphic annotation layers to be deleted

## ◆ removeTextObject()

OFCondition DVPSGraphicAnnotation_PList::removeTextObject | ( | const char * | layer,
|  | const char * | instanceUID,
|  | unsigned long | frame,
|  | size_t | idx
| ) |  |

deletes the text object (applicable to the current image and frame) with the given index on the given layer.

Parameters

  layer | name of the graphic layer
  instanceUID | SOP instance UID of the current image
  frame | number of the current frame
  idx | index of the text object, must be < getNumberOfTextObjects(layer)

Returns
  EC_Normal upon success, an error code otherwise

## ◆ renameLayer()

void DVPSGraphicAnnotation_PList::renameLayer | ( | const char * | oldName,
|  | const char * | newName
| ) |  |

renames the graphic annotation layer name in all activations with a matching old graphic annotation layer name.

Required to keep the presentation consistent when a graphic layer is renamed.

Parameters

  oldName | the old graphic annotation layer name
  newName | the new graphic annotation layer name

## ◆ usesLayerName()

OFBool DVPSGraphicAnnotation_PList::usesLayerName | ( | const char * | name | ) |

checks if the given layer name is used for any of the graphic annotation layers managed by this object.

Parameters

  name | name of the layer

Returns
  OFTrue if name is used

## ◆ write()

OFCondition DVPSGraphicAnnotation_PList::write | ( | DcmItem & | dset | ) |

writes the list of graphic annotations managed by this object to a DICOM dataset.

Copies of the DICOM elements managed by this object are inserted into the DICOM dataset.

Parameters

  dset | the dataset to which the GraphicAnnotationSequence is written

Returns
  EC_Normal if successful, an error code otherwise.

The documentation for this class was generated from the following file:

- dcmpstat/include/dcmtk/dcmpstat/dvpsgal.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1