DITA-FMx User Guide

Graphic Overlay Objects

Working with text callouts and simple graphic objects placed over a referenced image.

As of DITA-FMx 1.1, you can now include callouts and other graphic overlay objects in your DITA files. Although this is not specifically supported in DITA, the data to round-trip these objects is stored in nested data elements immediately following the image element within a fig. This support is only available for images that are child elements of a fig element.

DITA-FMx supports the following types of graphic objects as overlay objects within an anchored frame:

  • Line
  • Arc
  • Polyline
  • Rectangle
  • Rounded Rectangle
  • Oval
  • Polygon
  • Text Line
  • Text Frame (limited support)

Note that a Text Frame can only contain a single paragraph and the only properties that are saved are horizontal alignment and paragraph style. Other types of nested frames are not currently supported. Additionally, the object grouping mechanism is not supported.

The Text Line object uses the character style applied to the first character, and applies that style to all characters in the object. The Text Frame object stores the paragraph style name that is applied when it is created. Both of these styles, the character style for Text Line objects and the paragraph style for Text Frame objects, should be predefined in the Topic and Book templates so they will be formatted properly in the final output.

If you plan to edit callouts as XML (for localization or other purposes) you should not use the Text Line object. The dimensions of the text are stored in the data elements and will not update when you change the actual text. The result will be that the callout remains the same size with the text stretched or compressed to fit into the same area. If you plan to edit the callout text as XML, you should use the Text Frame object which defines the bounds of a region in which the text will flow.

The data stored in the nested data elements is very FrameMaker-specific, but can be translated into other formats such as SVG with a little effort. If your image element is within a fig element and contains graphic overlay objects, a data element will be inserted immediately following the image element. This data element will have the @datatype attribute set to “fm:imagedata”. Within this data element will be a child data element for each of the graphic overlay objects, and each will have a @datatype attribute set to a value appropriate for the object type (e.g. “fm:textline” for a TextLine object and “fm:polyline” for a Polyline object).

When written to XML, all of these data elements will be empty elements (just specifying @name and @value attribute values) except for the text of a Text Frame object. Because this content is likely to be modified for localization purposes, it is written to XML as content of the data element. On import to FrameMaker, this is converted to a data/@value.

Each of the child data elements will have the @value attribute set to a tilde-delimited string that specifies the property names and values. For some properties the associated value may be a very large numeric value, this is a FrameMaker “MetricT” value (this has nothing to do with the metric measurement system). When used for linear measurement, value of 65536 is equal to a point (1/72 inch).