com.ccg.awt
Interface ImageGenerator

All Known Implementing Classes:

ImageGen

public interface ImageGenerator

Definition of what a ImageGenerator must be able to do.

This interface defines a very "generic" method for a interpreter which is capable of creating and/or modify bitmap images (apply affects).

This interface is very generic, and one should refer to the ImageGen class for an example implementation (it also serves as a very usable/extendable base).

To get a better understanding of the goal of this interface, lets look at some examples of how this class might be used (if you want to try out a live working version, look at ImageGenerator.hmtl). For example, lets assume we wanted to make some fancy bitmap push buttons for a applet. The normal approach would be to create two separate bitmaps and download them to the applet. However this can consume a lot of bandwidth and can be time consuming to adjust your bitmaps. Instead of sending bitmaps, we can use a image generator and supply it with a simple set of commands to build our buttons for us. Look at the following two strings

 "@fill(200,50,red) @roundEdge(10,20)"
 "@fill(200,50,red) @roundEdge(10,-20)"
 

The first string uses a "@fill" command to create a bit map that is 200 pixels wide, 50 pixels tall and fills it with "red". The "@roundEdge" button then rounds the corners of our bitmap downwards to produce a button bitmap in "released" state.

The second string is almost identical to the first, except that it rounds the corners in a upwards fashion to produce a pushed button bitmap (via the -20 parameter).

This provides a very convienent foundation to build dynamic image scripting capabilities into your applications (and can greatly reduce the size of JAR files downloaded to applets).

It should be noted that this interfaces is very generic and doesn't enforce any rules about the format of the commands. However, all implementations should try to follow the general form of:

 @COMMAND([PARM1[,PARM2...]])
 

 
Where:

 


 
@COMMAND
Represents the name of the command. As an
 example, it might look like: "@fill".

 
PARMn
Each command may allow zero or more parameters
 (its up to the commands implementation). Each parameter will be
 separated by a comma. If necessary a parameter can be enclosed in
 double quotes and standard Java string escape characters can appear
 within the double quotes. The quoting would be required if a
 parameter contained a comma or parenthesis. For example,
 "@label(Paul,0,10)" is the same as "@label("Paul",0,10)",
 however, "@label(Paul, B,0,10)" is NOT the same as
 "@label("Paul, B",0,10)".

 
Comments
All text (white space, semicolons, regular
 characters, etc) outside of the scope of the commands should be
 ignored. This allows for commenting of the macros if desired. For
 example, the String: @fill(100,50,blue) @round(10,20)
 would be equivalent to a String containing the following text:

 
#
# Create a blue 100x50 bitmap
#
@fill(100,50,blue);

#
# Now, round the edges for a 3D button look
#
@round(10,20);
 

 

 
The above rules are for those that want to implement a ImageGenerator from scratch. Most people will be
 able to use the ImageGen class directly, or extend
 the ImageGen class to create their own custom
 interpreter.




Since:
  
1.0
Version:
  
$Revision: 1.3 $
Author:
  
$Author: pkb $
See Also:
ImageGenerator.hmtl, 
ImageGen, 
ImageHolder







Method Summary




 Image
interpret(Object modify,
          ImageHolder ih,
          String commands)



          Interpret a set of commands to create/modify a image.


 





Method Detail



interpret
Image interpret(Object modify,
                ImageHolder ih,
                String commands)
                throws Exception

Interpret a set of commands to create/modify a image.
 
 You have the following options when invoking this command:

 


 
Pass a 'null' starting image with the assumption and/or
 requirement, that one of the first commands interpretted will
 create the image for you.

 
Pass a starting image object assuming that the interpretor
 will be able to "apply" some affects to the object.

 


Parameters:
modify - This parameter can be any type of Java object, it will
        typically be 'null', a RGBPixels object, or
        some sort of Image object.
ih - This parameter serves as a way to provide a "library" of
        bitmap images to the interpreter. It should never be null, but
        its OK to pass a empty ImageHolder
        object. The interpreter is free to use this object to lookup
        additional bitmap resources as it builds its image.
commands - This is a set of commands which the interpreter understands to
        create/modify images.
Returns:
If the interpreter is able to successfully process the
        commands, it will return a Image
        object. It should never null - it throws an exception on
        failure.
Throws:
Exception
Since:
  
1.0
See Also:
ImageGen.interpret(java.lang.Object, com.ccg.awt.ImageHolder, java.lang.String)