ChartDirector Mark Up Language (CDML) is a language for including formatting
information in text strings by marking up the text with tags.
CDML allows a single text string to be rendered using multiple fonts, with
different colors, and even embed images in the text.
You can change the style of the text by using CDML tags. For example, the
line:
<*font=timesi.ttf,size=16,color=FF0000*>Hello <*font=arial.ttf,size=12,color=8000*>world!
will result in the following text rendered:
In general, all tags in CDML are enclosed by
<* and
*>.
Attributes within the tags determine the styles of the text following the tags
within the same block.
If you want to include
<* in text without being interpreted as CDML
tags, use
<<* as the escape sequence.
The following table describes the supported font style attributes in CDML. See
Font Specification for details on various font attributes.
Attribute | Description |
font
|
The font file name.
|
size
|
The font size.
|
width
|
The font width. This attribute is used to set the font width and height to different
values. If the width and height are the same, use the size attribute.
|
height
|
The font height. This attribute is used to set the font width and height to different
values. If the width and height are the same, use the size attribute.
|
color
|
The text color in hex format.
|
underline
|
The line width of the line used to underline the following characters. Set to 0 to
disable underline.
|
advance
|
Move the cursor forward (to the right) by the number of pixels as specified by the
value this attribute.
|
advanceTo
|
Move the cursor forward (to the right) to the position as specified by the value
this attribute. The position is specified as the number of pixels to the right
of the left border of the block. If the cursor has already passed through the
specified position, the cursor is not moved.
|
Note that unlike HTML tags, no double or single quotes are used in the tags. It
is because CDML tags are often embedded as string literals in source code. The
double or single quotes, if used, will conflict with the string literal quotes
in the source code. Therefore in CDML, no quotes are necessary and they must not
be used.
Also, unlike HTML tags, CDML uses the comma character as the delimiter between
attributes. It is because certain attributes may contain embed spaces (such as
the font file name). So space is not used as the delimiter and the comma
character is used instead.
In CMDL, a text string may contain multiple
blocks. A block may contain
multiple lines of text by separating them with new line characters ("\n") or
with
<*br*>. The latter is useful for programming languages that
cannot represent new line characters easily.
For example, the line:
<*size=15*><*block*><*color=FF*>BLOCK<*br*>ONE<*/*> and <*block*><*color=FF00*>BLOCK<*br*>TWO<*/*>
will result in the following text rendered:
The above example contains a line of text. The line contains two blocks with the
characters
" and " in between. Each block in turn contains two lines. The
blocks are defined using
<*block*> as the start tag and
<*/*>
as the end tag.
CDML supports embedding images in text using the following syntax:
<*img=my_image_file.png*>
where my_image_file.png is the path name of the image file.
For example, the line:
<*size=20*>A <*img=sun.png*> day
will result in the following text rendered:
ChartDirector will automatically detect the image file format using the file
extension, which must either png, jpg, jpeg, gif, wbmp or wmp (case
insensitive).
Please refer to
BaseChart.setSearchPath or
DrawArea.setSearchPath on the
directory that ChartDirector will search for the file.
CDML supports nesting blocks, that is, a block can contain other sub-blocks. Attributes
are supported in the
<*block*> tag to control the alignment and orientation
of the sub-blocks. The <*img=my_image_file.png*> is treated as a block
for layout purposes.
For example, the line:
<*block,valign=absmiddle*><*img=molecule.png*> <*block*>Hydrazino\nMolecule<*/*><*/*>
will result in the following text rendered:
The the above starts
<*block,valign=absmiddle*> which specifies its content
should align with each others in the vertical direction using the
absolute middle
alignment. The block contains an image, followed by a space characters, and then another
block which has two lines of text.
The following table describes the supported attributes inside
<*block*> tag:
Attribute | Description |
valign
|
The vertical alignment of sub-blocks. This is for blocks that contain sub-blocks.
Supported values are baseline, top, bottom, middle
and absmiddle.
The value baseline means the baseline of sub-blocks should align with
the baseline of the block. The baseline is the underline position of text. This is
normal method of aligning text, and is the default in CDML. For images or blocks
that are rotated, the baseline is the same as the bottom.
The value top means the top line of sub-blocks should align with
the top line of the block.
The value bottom means the bottom line of sub-blocks should align with
the bottom line of the block.
The value middle means the middle line of sub-blocks should align
with the the middle line of the block. The middle line is the middle position
between the top line and the baseline.
The value absmiddle means the absolute middle line of sub-blocks
should align with the absolute middle line of the block. The absolute middle
line is the middle position between the top line and the bottom line.
|
halign
|
The horizontal alignment of lines. This is for blocks that contain multiple lines.
Supported values are left, center and right.
The value left means the left border of each line should align with
the left border of the block. This is the default.
The value center means the horizontal center of each line should
align with the horizontal center of the block.
The value right means the right border of each line should align
with the right border of the block.
|
angle
|
Rotate the content of the block by an angle. The angle is specified in degrees
in counter-clockwise direction.
|
© 2004 Advanced Software Engineering Limited. All rights reserved.