Module 3- Working with Text

Overview
In the first two modules, we learned how to create a window with a QTCanvas and use a compositor to display an image and a movie. This module expands upon that example and uses QuickTime's text services to render text (see image, right).

In this module, we will learn how to specify font characteristics such as font, size, face, and color, and will also explore how to use graphics modes of the compositor.

NOTE: This feature requires QuickTime for Java 4.1. It will not work with previous versions.

Introduction to Drawing Text in QuickTime for Java

QuickTime for Java has a built-in text engine that is based on QuickDraw's text support. This approach is extremely simple and allows us great control over text sizes, faces, and fonts. Unfortunately, this simplicity comes at a bit of a price- it up to the developer to make sure that the specified font exists and to perform any necessary scaling as needed by the native platform. If you need robust, cross-platform font support, consider using Java to do text drawing.

Setting up the Project

This project is based on the previous module and assumes that you have completed it. If you would like to download a completed copy of the module 2, you may do so. Before proceeding, we have renamed the main class to "Zoo3" and changed all instances to prevent confusion. Other than that, we do not need to modify the main class file.

Click here to see the main source file Zoo3.java.

We will need to create a new source file for our class that will contain all of our text drawing code. We will call this class TextPresenter. Create a new source file and save it as TextPresenter.java. Now we will create a skeleton for our class:

import java.awt.Dimension;
import java.io.FileNotFoundException;

public class TextPresenter
{
    public TextPresenter( String filePath, Dimension size )  
           throws FileNotFoundException
    {
       this( TextPresenter.readTextFile( filePath ), size ); 	
    }

    public TextPresenter( String[] text, Dimension size )
    {

    }

    public static String[] readTextFile( String filePath ) 
           throws FileNotFoundException
    {

    }
}

Our class is responsible for rendering text into an area such as a portion of a QTCanvas or into a compositor. We create two constructors, one that takes the path of a text file to be loaded and rendered along with a bounding rectangle for the text, and the second takes an array of strings and a dimension of the text area. We also declare a utility routine called readTextFile( ). This routine will read a file specified by the filePath argument and return an array of strings as its argument.

We provide two different constructors for convenience. We allow the user to either specify the text data to be drawn as an array of strings, or specify a text file to be used for the data. The first constructor simply calls the second constructor with the results of the call to readTextFile( ) as the constructor parameter.

Back to top

Importing Packages and Creating an Offscreen Graphics Context

Now we are ready to start fleshing out our second constructor. In our constructor, we will need to do three different things. The first is to create an offscreen drawing area large enough for the specified dimension. Secondly, we need to take the string array and draw it in the offscreen drawing area. Lastly, we need to take our offscreen drawing area and put it into a format that we can draw into the compositor.

Let's start to flesh out the constructor to do the first of these three tasks:

import java.awt.Dimension;
import java.io.FileNotFoundException;

import quicktime.qd.QDGraphics;
import quicktime.qd.QDRect;

import quicktime.QTException;

public class TextPresenter
{
    public TextPresenter( String filePath, Dimension size )  
           throws FileNotFoundException
    {
       this( TextPresenter.readTextFile( filePath ), size ); 	
    }
    public TextPresenter( String[] text, Dimension size )
    {

        final QDRect area = new QDRect( size );

        try
        {
            gw = new QDGraphics( area );
        }
        catch ( QTException e )
        {
            e.printStackTrace();
        }

    } 
    public static String[] readTextFile( String filePath ) 
           throws FileNotFoundException              
    { 
    } 
}

protected QDGraphics gw;

The first thing we do is import three QTJ packages. The first is QDGraphics. This class encapsulates the behavior of a traditional Macintosh quickdraw color graphics port. This port is a complete graphics drawing environment that specifies when and how graphics operations occur.

We then import the QDRect class that defines a QuickDraw Rectangle structure.

Lastly, we import the QTException class. This type of exception may be thrown by many of the routines that we will be using.

Once we import the necessary classes, we are ready to implement the body of our TextPresenter constructor.

We start our body with the declaration of a QDRect variable named area. This is declared so that we can have a QuickDraw representation of the dimension object that is passed in to our constructor.

Next we declare a try( ) block. This will allow us to catch any QuickTime errors thrown by the various methods that we will be calling. Within our try( ) block, we create a new QDGraphics object and pass it the area QDRect data member. This QDGraphics object named gw, declared down at the end of the file, contains a 32-bit per pixel offscreen graphics world and all of the associated QuickDraw data structures such as the color table and the PixMap. The constructor we used specifies a default set of creation flags and locks the GWorld into memory. The parameter we pass specifies the size of the offscreen GWorld.

Finally, we close the try( ) block and make a catch( ) block that handles any QTExceptions thrown and prints a stack trace if an exception occurs. Note that this is extremely rudimentary error handling and is simplified for the purpose of this tutorial. Real applications should provide more robust error and exception handling.

So far, we have created a QDRect to represent the size of the offscreen area (based on the dimension parameter of our constructor) and created a QDGraphics object that encapsulates our GWorld we will be drawing in. Now it's time to perform the actual text drawing.

Back to top

Creating a QDDrawer Object

import java.awt.Dimension;
import java.io.FileNotFoundException;

import quicktime.qd.QDGraphics;

import quicktime.qd.QDDrawer;

import quicktime.qd.QDRect;

import quicktime.QTException;

public class TextPresenter
{
       ...

    public TextPresenter( String[] text, Dimension size )
    {
        final QDRect area = new QDRect( size );

        try
        {
            gw = new QDGraphics( area );

       
            gw.beginDraw( new QDDrawer()
            {
                public void draw( QDGraphics gw ) 
                     throws QTException
                {
                }
            }); 

        }
        catch ( QTException e )
        {
            e.printStackTrace();
        }   
    } 

        ...

Now that we have a QDGraphics object to draw into, we need to create an object that will perform the actual drawing in the GWorld. We will be using a QDDrawer object for simplicity. This class has a single draw( ) method that we can override to do our custom drawing.

First we import the QDDrawer package. Next, we call beginDraw( ) from the QDGraphics object and pass a new QDDrawer( ) anonymous class that we declare inline. Our anonymous class overrides the draw( ) method and declares that it throws a QTException. (Now it is evident why we need the try/catch block around our code.)

The beginDraw method is called whenever the QDGraphics object needs to update the contents of its offscreen gWorld. This typically only occurs once (at initialization). Now we can place any drawing code directly in the draw method and it will be transferred into the contents of the offscreen GWorld.

Back to top

QuickDraw Text Drawing Operations

Drawing in a QuickTime graphics context is accomplished by means of calling standard QuickDraw commands. All operations are called via methods of a QDGraphics object:

public class TextPresenter
{
       ...

    public TextPresenter( String[] text, Dimension size )
    {
        final QDRect area = new QDRect( size );

        theText = text;

        try
        {
            gw = new QDGraphics( area );
            gw.beginDraw( new QDDrawer()
            {
                public void draw( QDGraphics gw ) 
                     throws QTException
                {

                    gw.textSize( 12 );
                    gw.textFont( QDFont.getFNum("Times") ); 
                    gw.textFace( QDConstants.normal );
                    gw.setForeColor( QDColor.black );
							          
                    gw.setBackColor( QDColor.white );
                    gw.eraseRect( area );
									
                    String aLine = theText[0];
									
                    if ( gw.textWidth( aLine, 0, aLine.length() )
                                              > area.getWidth() )
                        gw.textSize( 10 );
									
                    for ( int i = 0; i < theText.length; ++i )
                    {
                        if ( i != 0 )
                            aLine = theText[ i ];
                        gw.moveTo( 0, (i+1) * 12 );
                        gw.drawTextScaled( aLine.length(), 
                            aLine, 1.0f, 1.0f );
                    }

                }
            });       
        }
        catch ( QTException e )
        {
            e.printStackTrace();
        }   
    } 

        ...
}

protected QDGraphics gw;

protected String[] theText;

First, we declare a local copy of the text parameter that is passed in to our constructor. This is neccesary because we cannot access this parameter from inside an anonymous inner class. This data member is declared at the end of the file as a String array.

Now, we need to set up our graphics environment. We set the size of the font we will be using by calling the textSize( ) method. This allows us to specify the font size in points to be used by subsequent drawing operations. In the same manner, we set the font, style, and color.

Next, we specify the background graphics color (the color that will be used for erasing operations), and erase the entire contents of the QDGraphics. It is very important that we perform this erase operation because when the QDGraphics object is created it is a chunk of uninitialized memory which would translate to randomly colored pixels. This erase operation gives us a clean "canvas" to draw on.

Now we need to get the text to draw. We create a temporary String object and initialize it to the first item in the String array that is passed in to our constructor. Once we have this string, we check the width in pixels of the string and compare it to the width of our drawing area. If the text is too long to fit in the specified space, we decrease the font size. This adjustment is designed to account for font size differences between the Macintosh platform and windows. This rough adjustment works for this particular scenario, but is not a robust way to perform cross-platform font adjustment.

Finally, we declare a for loop:

for ( int i = 0; i < theText.length; ++i ) {

We will take one trip through our loop for each String in our array. Since we have already assigned the first item in our String array constructor parameter to our aLine data member, we skip this first item. All subsequent items will be assigned to this temporary variable in sequence.

if ( i != 0 )
   aLine = theText[ i ]; 

We now have the string that we are going to draw. Now it is time to specify the location where the line of text will be drawn. This is done with a moveTo( ) call. This does not actually draw the text. Drawing text is accomplished via the drawTextScaled( ) method:

gw.moveTo( 0, (i+1) * 12 );
gw.drawTextScaled( aLine.length(), aLine, 1.0f, 1.0f );

The drawTextScaled( ) method takes four parameters. The first is the length of the string to draw and the second String parameter is the line that we will be drawing. The final two float parameters specify scaling. The first variable specifies horizontal scaling, while the second scaling variable specifies vertical scaling. A value of 1.0 represents 100% scaling while a value of .5 would specify 50% (half size) and 2.0 would represent 200% scaling (double size).

This completes our text drawing operations. Now we need to provide the graphics context in a format that the compositor can use for drawing.

Back to top

Setting the Graphics Mode of the QDGraphics Object

Now that we have drawn the text, we need to prepare the graphics object for drawing by the compositor:

public class TextPresenter
{
       ...

    public TextPresenter( String[] text, Dimension size )
    {
        final QDRect area = new QDRect( size );

        try
        {
            gw = new QDGraphics( area );
            gw.beginDraw( new QDDrawer()
            {
                public void draw( QDGraphics gw ) 
                     throws QTException
                {
           
                    ...

                }
            }); 

            imagePres = ImagePresenter.fromGWorld( gw );
            imagePres.setGraphicsMode( new GraphicsMode( 
                  QDConstants.transparent, QDColor.white ));

        }
        catch ( QTException e )
        {
            e.printStackTrace();
        }   
    } 

        ...
}

public ImagePresenter getPresenter()
{
    return imagePres;
}

protected QDGraphics gw;
protected String[] theText;

protected ImagePresenter imagePres;

Preparing the graphics object for drawing is rather simple. First, we create a new ImagePresenter object by calling the fromGWorld( ) method, passing our QDGraphics object as the parameter. This gives us a new ImagePresenter object, capable of drawing the contents of the QDGraphics object and being added to the compositor. The ImagePresenter object is declared at the bottom of the file as a protected data member.

Next, we set the graphics mode of the ImagePresenter object. The graphics mode is the QuickDraw transfer mode used to draw the graphics. We have specified a transparent mode and used white as the transparent index. This will treat all white pixels with an RGB value of 255, 255, 255 as transparent pixels. This enables us to draw our text on top of the background without obscuring the image.

Since the ImagePresenter object is protected, we will need to add an accessor routine that external classes can use. We add a method called getPresenter( ) that simply returns our imagePres data member. This is a better object-oriented programming technique than simply making the imagePres object public.

Back to top

Completing the Class

All that remains is to write the method that reads in the text file:

public class TextPresenter
{
       ...

    public TextPresenter( String[] text, Dimension size )
    {
       ...
    }

    public static String[] readTextFile( String filePath ) 
        throws FileNotFoundException
    {
        if (filePath != null)
        {
            try
            {
                BufferedReader reader = new BufferedReader( 
                    new FileReader( filePath ));
                Vector lines = new Vector();
				
                String aLine = reader.readLine();
                while ( aLine != null )
                {
                    lines.addElement( aLine );
                    aLine = reader.readLine();
                }
				
                String[] lineArray = new String[lines.size()];
                lines.copyInto( lineArray );
                return lineArray;
            }
            catch ( IOException exc )
            {
                exc.printStackTrace();
            }
        }
		
        return new String[0];
    }

}

protected QDGraphics gw;
protected String[] theText;
protected ImagePresenter imagePres;

We declare the readTextFile to return a static array of Strings and take a String file path parameter. We also declare that the method may throw a FileNotFoundException if the path is invalid. This code is pure Java code and doesn't involve QuickTime, so we won't examine it in detail. Basically, we create a new file reader object and read single lines from the file, placing each line into the string array which is returned at the end of the method.

Back to top

Modifying AnimalPane

Now, we will return to the Animal Pane file for minor modifications to add the ImagePresenter to the compositor:

    ...

public class AnimalPane
{
    public AnimalPane()
    {

        QDRect size = new QDRect(Zoo3.WIDTH, Zoo3.HEIGHT);

        try
        {
            QDGraphics gw = new QDGraphics( size );
            compositor = new Compositor( gw, QDColor.white, 
                                         30, 1 );
		
            QTFile imageFile = new QTFile( 
                   QTFactory.findAbsolutePath( 
                   "data/zebra/ZebraBackground.jpg" ));
            GraphicsImporterDrawer drawer =
                   new GraphicsImporterDrawer( imageFile );
            ImagePresenter presenter = ImagePresenter.
                   fromGraphicsImporterDrawer( drawer );
            presenter.setLocation( 110, 110 );

            compositor.addMember( presenter, 3 );
            addText( "data/zebra/Zebra.txt", 2, 15, 160, 
                     415, 220 );

            Movie m = makeMovie( new QTFile( QTFactory.
                   findAbsolutePath( "data/zebra/Zebra.mov" )));
            md = new MoviePresenter( m );

                ...
            

First, we must do a little bookkeeping and update the references to the Zoo2 class to Zoo3. Next, we change the layer number of our ImagePresenter that displays the background image. We need to change this number from a two to a three so that it remains the bottom most layer with the movie on top and the text sandwiched in the middle:

Lastly, we make a call (which we will implement later) to add our text item to the compositor. This method will retrieve the ImagePresenter object from our TextPresenter class and position it in the compositor in a specific layer and at a specific location. This routine will take the path of the text to display, the layer number to display in the compositor, the x and y location within the compositor, and the height and width of the text area. We will implement this routine next.

Back to top

Implementing the addText Routine

The addText( ) routine is responsible for imaging our TextPresenter at a specific location in the compositor:

    ...

public class AnimalPane
{
    public AnimalPane()
    {
        ...
    }

    public Compositor getCompositor( ) { return compositor; }

    protected void addText( String textPath, int layer, 
                            int x, int y, int width, int height )
    {
        try
        {
            TextPresenter text = new TextPresenter( textPath, 
                new Dimension( width, height ));
			
            ImagePresenter presenter = text.getPresenter();
            Matrix theMatrix = new Matrix();
            theMatrix.translate((float) x, (float) y );
            presenter.setMatrix( theMatrix );
            compositor.addMember( presenter, layer );
        }
        catch( QTException e )
        {
            e.printStackTrace();
        }
        catch( FileNotFoundException e )
        {
            e.printStackTrace();
        }	
    }

    protected Movie makeMovie( QTFile f ) 
        throws IOException, QTException
    {
        ...	

As previously mentioned, the routine takes 6 parameters: a string path to the text file, the layer to be used in the compositor, the horizontal and vertical position of the text within the compositor, and a height and width of the text area.

All of our code is placed in a try block so that we can catch any exceptions that might be thrown by the TextPresenter constructor, or any subsequent routines.
First, we declare a TextPresenter object called text and call its constructor with the textPath and a Dimension object which we create inline.

Now we will need to get the ImagePresenter object from our TextPresenter. The ImagePresenter used by the TextPresenter is protected, so we will need to call a method to retrieve it. We call the getPresenter( ) method of the TextPresenter class for this purpose and store the result in a local object reference.

Our constructor has parameters for specifying the location of the text display area within the compositor. Offsetting the location of our TextPresenter is accomplished by using a matrix. QuickTime's Matrix classes are standard 3x3 matrices that allow us to specify translation (offsetting an object on the x and/or y axis in the cartesian coordinate system), scaling, or rotation of an object. We use the Matrix to specify a translation.

First, we create a new Matrix by calling the default constructor. This creates a new instance of the identity matrix. If we were to apply the identity matrix to an object, there would be no visible change. (For more information on Matrices, see this QuickTime document).

Next, we call the translate method of the matrix object to offset the text based on the x and y positions that are passed in to the routine as parameters. Once the translation matrix is calculated, we set the matrix of the presenter to the one we just created.

Finally, we add the text presenter to the compositor in the correct layer and perform any needed exception handling.

This completes source modifications for this module. If you would like to see completed source code for Zoo3.java, AnimalPane.java, or TextPresenter.java, please click on the appropriate link.

Back to top

Summary

This module introduced the basics of dealing with text using the QuickTime text engine.

We learned how to create a graphics context for drawing using basic QuickDraw commands and used QuickDraw transfer modes to modify the appearance of the drawn image. Finally, we used an intermediary ImagePresenter object to display our rendered text area in a compositor.

We covered a lot of material, and in our next section, we will switch gears and learn about how to add sound playback to our application.

Back to top

Further Exploration

The clever reader will realize quickly that the information that was presented here only scratches the surface of what could be done using QuickTime for Java. Although we will expand this example in future modules, there are few things that you could do on your own as exploration that will help you better understand how QuickTime for Java works.

Each one of these examples has a source code solution, so if you have trouble, feel free to consult it.

Experiment with one or more of the following:

1. Change the font, text face, and size.
2. Modify the graphics code so that the first character of the paragraph is drawn with a large initial capital.
3. Center align the text. (You will need to compute the length of each line and change the intial point where each line is drawn.
4. Apply a graphics mode to the text so that it draws semi-transparently over the zebra background.
5. For the super genius, implement a rudimentary html parser so the text file can be an html file.