Adding Text to an Image in Cold Fusion with csImageFile

The csImageFile component can be used to add text to images and this page explains some of the properties and methods used, and provides some example code fragments for Cold Fusion. In all the code examples we will assume the csImageFile object has been called "Image". For single lines of code we will miss out the cfscript or cfset tags.

Font and Font Properties

The font face is specified by the TextFont string property. It can be set to any font installed on the system. For example:

Image.TextFont = "Arial"

*Note* - Fonts installed on a remote server using Terminal Services cannot be used until the server is rebooted. If the fonts are installed by someone who is logged on as an Administrator they can be used immediately.

There is a separate property for colour, size and for each of the styles bold, italic, underline and strikeout (TextColor, TextBold, TextItalic, TextUnderline, TextStrikeout). The area behind the text will be the colour of TextBG if TextOpaque is true. Setting TextOpaque to false makes the text background transparent.

So for red bold text with a transparent background we would have:

<cfscript>
Image.TextColor = "FF0000";
Image.TextBold = true;
Image.TextOpaque = false;
</cfscript>

Positioning Text

The text is placed on the image using the Text method, which takes the X and Y coordinates and the text string as parameters. The coordinates are measured from the top left corner of the image. For example:

Image.Text(10, 50, "The output text");

By default, the text is written horizontally from left to right. This can be changed by setting the TextAngle property. This sets the angle of rotation in degrees measured anticlockwise from the horizontal, so setting TextAngle to 90 will produce text written vertically up the page.

Often it is useful to know the width or height of a piece of text and the TextWidth and TextHeight functions do this. They return the width or height that a specified string would be if it was drawn using the current settings. For example, the following will write "Hello" at the bottom right corner of the image:

Image.Text(Image.Width - Image.TextWidth("Hello"), Image.Height - Image.TextHeight("Hello"), "Hello");

The following code will write "Hello" at the bottom right corner of the image, but it will be written vertically up the page:

<cfscript>
Image.TextAngle = 90;
Image.Text(Image.Width - Image.TextHeight("Hello"), Image.Height, "Hello");
</cfscript>

Justification and Carriage Returns

Text can be made to span multiple lines by adding carriage returns to the string in the Text command. In fact a line feed, a carriage return or both will have the same effect:

Image.Text(0, 0, "First line" & Chr(13) & "Second line");

Multi line text can be justified by setting the TextJustify property. The default is 0 (left justified) but it can be set to 1 for centre justified and 2 for right justified. The X parameter of the Text command is always the left most part of the block of text.

Multi line text could also be written one line at a time by repeatedly calling the Text command and adding the height of a line to the Y coordinate each time.

* Note * An alternative method of drawing multi line text is available in the form of the TextWrap, TextRectX and TextRectY properties. When TextWrap is true the text will wrap to fit a rectangular area. Text drawn this way is always left justified.

Antialiased Text

Text can be drawn with an antialiased effect by setting the Antialias property to true. This makes the edges of the text smoother but the image must have a colour depth of 24 bit. The NewImage command creates 24 bit images but if a lower colour depth image like a GIF has been loaded, the ColorDepth property must be set to 24. Antialias uses Windows Font Smoothing which does not apply to small font sizes.

An alternative antialising is provided by the BlurText property. This applies a filter as specified by FilterType and it has a more diffuse effect than using Antialias. It applies to all text sizes and automatically converts an image to 24 bit. Here are examples of text drawn without antialiasing, with antialiasing and with blurring.

<cfscript>
Image.TextSize = 24;
Image.TextOpaque = false;
Image.Text(10, 10, "Plain Text");
</cfscript>

<cfscript>
Image.TextSize = 24;
Image.TextOpaque = false;
Image.Antialias = true;
Image.Text(10, 10, "Antialiased Text");
</cfscript>

<cfscript>
Image.TextSize = 24;
Image.TextOpaque = false;
Image.BlurText = true;
Image.Text(10, 10, "Blur Text");
</cfscript>

Partially Transparent Text

Text can be given a percentage transparency value to blend it with the background. This is done by setting the TextTransPercent property before drawing any text. This is a relatively new property introduced in December 2007.

<cfscript>
Image.TextSize = 24;
Image.TextOpaque = false;
Image.Antialias = true;
Image.TextTransPercent = 70;
Image.TextColor = "FFFFFF";
Image.Text(30, 10, "Watermark");

For a full list of available Cold Fusion examples and tutorials - Click Here