Using Montage Pictures in your own Java programs

Montage has an Application Programmer's Interface (API) you can use to load and display pictures created with Montage from within your own Applets or standalone Java applications. The API also lets you query the picture about the size, name and location of each of the zones it contains. Different programs can give different meanings to zone information. A data entry Applet can use it to position each of the fields in a form while a video game might use it to mark the location of monsters, weapons and obstacles for each level of the game.

The API consists of classes Picture, Zone, GT, Mat2D in the com.ludens.api package.

An Example

This is the complete source code for an Applet that retrieves and displays a Montage picture. All references to the Montage API are in bold typeface:

import java.applet.*;
import java.awt.*;
import com.ludens.api.*;

public class MontageAPIDemo extends Applet {

    Picture picture;

    public void init()
    {
        picture = new Picture(this, "demo.teq");
    }

    public void paint(Graphics g)
    {
        picture.draw(g);
    }

}

In order to compile and run this example need to install a copy of the MONTAGE API classes in the same directory where you are placing your source code. You can get a copy of the API classes by typing GetAPI at the operating system's command prompt.

Class Picture

A Picture is a list of graphic items and Zones.
It knows how to draw itself and can use different criteria to search among its Zones.

Picture: Constructors


Picture(Component parent,
        String name)

parent is the java.awt.component where the picture will be drawn.
name is the name of the file that contains the picture. If parent is a java.applet.Applet then name will be used as part of the progress indicator while parsing the picture.


Picture(Component parent,
        String name,
        int width,
        int height)


Picture(InputStream is,
        Component parent,
        String name)

The picture is read from the java.io.InputStream is.
parent is the java.awt.component where the picture will be drawn.
If parent is a java.applet.Applet and name is not null then name will be used as part of the progress indicator while parsing the picture.


Picture(InputStream is,
        Component parent,
        String name,
        int width,
        int height)

Picture: Constants



final static int EXACT_MATCH;

Used in Zone lookups to indicate that the search pattern must be identical to the number stored in the flags instance variable for a match to occur.



final static int PROP_MATCH;

Used in Zone lookups to indicate that at least one of the bits that are set in the search pattern must also be set in the flags instance variable for a match to occur.

Picture: Public Variables


int width;

The width of the picture in pixels.


int height;

The height of the picture in pixels.


Color backgroundColor;

The background color for the picture.

Picture: Static Methods


static Picture[] getPictures(Component parent,
                             String name)

Reads a multi-picture file.
parent is the java.awt.component where the pictures will be drawn.
name is the name of the file that contains the pictures. If parent is a java.applet.Applet then name will be used as part of the progress indicator while parsing the pictures.


static Picture[] getPictures(Component parent,
                             String name,
                             int width,
                             int height)


static Picture[] getPictures(InputStream is,
                             Component parent,
                             String name)

Reads a multi-picture file.
The pictures are read from the java.io.InputStream is.
parent is the java.awt.component where the pictures will be drawn.
If parent is a java.applet.Applet and name is not null then name will be used as part of the progress indicator while parsing the pictures.


static Picture[] getPictures(InputStream is,
                             Component parent,
                             String name,
                             int width,
                             int height)

Picture: Methods


void draw(Graphics g)

Draw the picture using java.awt.Graphics g.


void draw(Graphics g,
          int x,
          int y)

Draw the picture using java.awt.Graphics g.
The upper left corner of the picture is drawn at coordinates x, y.


void draw(GT gt)

Draw the picture transformed by GT gt.
Text, Images, and Painters are ignored when drawing a transformed picture.


Zone contains(int x,
              int y)

Returns the topmost Zone under coordinates x, y (relative to top left corner of the picture) or null if there isn't a Zone at that location.


Zone getZone(String label)

Returns the topmost Zone labelled label or null if there isn't any Zone with that label.


Enumeration getAllZones()

Returns a java.util.Enumeration with all the Zones in the picture.


int zoneCount()

Returns the number of Zones in the picture.


Zone contains(int x,
              int y,
              int pattern,
              int matchType)

Returns the topmost Zone under coordinates x, y (relative to top left corner of the picture) that satisfies the search criteria or null if there isn't a Zone that satisfies the search criteria at that location.
If matchType is EXACT_MATCH then a Zone satisfies the search criteria when its flags instance variable is equal to pattern.
If matchType is PROP_MATCH then a Zone satisfies the search criteria when any of the bits set in pattern is also set in its flags instance variable.


Zone getZone(String label,
             int pattern,
             int matchType)

Returns the topmost Zone labelled label that satisfies the search criteria or null if there isn't any Zone with that label that satisfies the search criteria.
If matchType is EXACT_MATCH then a Zone satisfies the search criteria when its flags instance variable is equal to pattern.
If matchType is PROP_MATCH then a Zone satisfies the search criteria when any of the bits set in pattern is also set in its flags instance variable.


Zone getZone(int pattern,
             int matchType)

Returns the topmost Zone that satisfies the search criteria or null if there isn't any Zone that satisfies the search criteria.
If matchType is EXACT_MATCH then a Zone satisfies the search criteria when its flags instance variable is equal to pattern.
If matchType is PROP_MATCH then a Zone satisfies the search criteria when any of the bits set in pattern is also set in its flags instance variable.


Enumeration getAllZones(int pattern,
                        int matchType)

Returns a java.util.Enumeration with all the Zones in the picture that satisfy the search criteria.
If matchType is EXACT_MATCH then a Zone satisfies the search criteria when its flags instance variable is equal to pattern.
If matchType is PROP_MATCH then a Zone satisfies the search criteria when any of the bits set in pattern is also set in its flags instance variable.


int zoneCount(int pattern,
              int matchType)

Returns the number of Zones in the picture that satisfy the search criteria.
If matchType is EXACT_MATCH then a Zone satisfies the search criteria when its flags instance variable is equal to pattern.
If matchType is PROP_MATCH then a Zone satisfies the search criteria when any of the bits set in pattern is also set in its flags instance variable.

Class Zone

A Zone is a passive data structure that holds the information about a rectangular zone of a Picture.

Zone: Public Variables


int x;

The horizontal position of the upper left corner of the zone (relative to the upper left corner of the Picture that contains it).


int y;

The vertical position of the upper left corner of the zone (relative to the upper left corner of the Picture that contains it).


int width;

The horizontal size of the zone.


int height;

The vertical size of the zone.



String label;

The zone's label.



int flags;

Only the 16 least significant bits of flags are used.

Class Mat2D

Represents a sequence of 2D transformations (translation, rotation, scaling).

Mat2D: Public Variables



float tx;

X coordinate of a 2D point after applying the sequence of 2D transformations.



float ty;

Y coordinate of a 2D point after applying the sequence of 2D transformations.

Mat2D: Methods


Object clone()

Returns a copy of the Mat2D instance.


void translate(float xTrans,
               float yTrans)

Prepends a translation to the sequence of 2D transformations.


void scale(float xScale,
           float yScale)

Prepends a change of scale, relative to (0, 0), to the sequence of 2D transformations.


void rotate(int angle)

Prepends a rotation, around (0, 0), to the sequence of 2D transformations.


void transform(float x,
               float y)

Applies the sequence of 2D transformations to a point (x, y). The coordinates for the transformed point can be fetched from tx, ty.

Class GT

Geometric Transformations. Basic support for drawing a hierarchy of transformed lines and polygons.

GT: Constructor


GT(Graphics g)

g is the graphics context used to draw the lines and polygons.

GT: Public Variables


Graphics g;

g is the graphics context used to draw the lines and polygons.


Mat2D matrix;

matrix is the current transformation matrix.

GT: Methods


void pushMatrix()

Pushes a copy of the current transformation matrix on top of the transformations stack.


void popMatrix()

Pops the top of the tranformations stack and uses it to replace the current transformation matrix.


void vertexStart()

Starts a new list of transformed vertices.


void fillPolygon()

Uses the current list of transformed vertices to fill a polygon.


void drawPolygon()

Uses the current list of transformed vertices to draw a polygon.


void drawLine()

Uses the current list of transformed vertices to draw a line.


void addVertex(float x,
               float y)

Transforms the point (x, y) and adds it to the transformed vertices list.