Introduction

The Microsoft com.ms.fx (Fx) package for Java provides graphics and effects classes and interfaces. The Fx package provides a base framework for many other Microsoft packages, and it is a key element in making the Microsoft® Application Foundation Classes™ (AFC) both Java Development Kit (JDK) 1.0.2 and 1.1 compatible. The com.ms.fx package provides the following support:

• Extensible, cross-platform graphics for the AFC libraries.
• Support for formatted text in any language and for characters not defined in Unicode.
• Text rotation and vertical writing support for internationalization (i18n).
• Support for windowless components and controls.
• User-configurable texture and Image class factories.
• A drawing primitives API based on java.awt.Graphics.

This article provides an overview of the basic features of the com.ms.fx package. In addition, it covers programming with the extensible drawing classes, provides an in depth look at the texture and image class factories, and describes integration of various aspects of the Fx package with controls and features from other Microsoft packages.

Package Overview

The Microsoft com.ms.fx package contains classes that fall into several broad categories.

The core classes of the Fx package handle most of the common graphics operations.

FxGraphics	The FxGraphics class is derived from the java.awt.Graphics class and provides an extended graphics object implementation and abstract methods for full cross-platform compatibility.
FxFormattedText	The FxFormattedText class supports formatted text buffers written in any language and drawn in any direction.
Region	The Region class provides a data structure for shape manipulation, and also helps support the windowless architecture in AFC.
FxFont	The FxFont class manages user-defined font objects and is the base for extended font objects in the Fx package.
FxColor	The FxColor class provides both JDK 1.0.2 and JDK 1.1 compatible color objects for AFC, as well as a base for extended color objects in the Fx package.

Classes that extend from FxColor are used with the drawing primitives API provided in the FxGraphics class to increase the flexibility of drawing operations. These extended color classes include the following:

FxFill	FxTexture	FxPen
FxBrushPen	FxRubberPen	FxStyledPen

The com.ms.fx package includes classes that provide a set of consistent, cross-platform system images and icons. These classes include texture and image factory classes that can provide texture and image sets for components in various states. These image and texture classes include the following:

FxStateConfigurableImage	FxStateConfigurableUIImage	FxComponentImage
FxComponentTexture	FxSystemIcon

The text buffer and font classes handle text buffers and drawing, and they rely on a number of supporting low-level Fx classes, which are rarely manipulated directly.

fullTxtRun	txtRun	FxCurve	FxEllipse
OutlinePolygon	OutlineCurve	GlyphOutline	GlyphMetrics
FloatPoint

The FxToolkit class provides both VM-specific support to other AFC classes and helper objects that assist with tasks such as dialog box loading and image loading.

Technical Overview

Extended Color and Font Objects

If you have not done any graphics programming in Java, you will find that it is basic and intuitive using AFC. If you are familiar with graphics programming using the java.awt package, especially the java.awt.Graphics class, the transition to programming with Fx extended color and font objects will be a smooth one.

Graphics operations in Java are performed with a graphics object. Using java.awt, you can obtain this graphics context with the call

Graphics g = this.getGraphics();

and set the graphics context to a specified color, font, paintmode, and so on. The com.ms.fx package provides extended graphics objects, derived from java.awt.Graphics, to overcome limitations imposed by the Graphics class. FxGraphics objects can be used just like a Graphics object, inheriting its drawing API from java.awt.Graphics. The com.ms.ui package supports both paint(Graphics g) and paint(FxGraphics) methods.

Part of the power of the com.ms.fx package is the ability to use extended color and font objects in place of Color or Font within a graphics context. The extended color and font classes included with the com.ms.fx package have special attributes.

For example, the FxPen class provides a drawing object that is multiple pixels wide. This seems relatively simple, but in comparison, the java.awt package provides no way to draw primitives that are multiple pixels wide -- short of coding repetitous drawing operations. The following example draws many ovals, 1 pixel wide, using standard AWT programming. The result is a thick oval, drawn in the current color.

// Override the paint method in an applet 
// to draw a thick oval.
public void init{
  setBackground(Color.black);
}

public void paint(Graphics g) {
  for(int x = 2;x<10;x++)
  {
    g.drawOval(x, x, 60-(2*x), 40-(2*x));
  }               
}

The same oval can be drawn easily with an FxPen object. You retrieve an extended graphics object by using the static method call, FxGraphics.getExtendedGraphics.

// Override the paint method in an applet to draw a thick oval.
public void init{
    setBackground(new FxPen(8, Color.black));
}

public void paint(FxGraphics g) {
    fxGraf.drawOval( 2, 2, 60, 40);
}

The FxFont and FxColor objects and their derivatives are set to an extended graphics object the same way the java.awt.Font and java.awt.Color objects are. The method calls are the same (setColor, setFont) regardless of the object selected into the graphics context. In this way, the com.ms.fx package is fully compatible with AWT.

The com.ms.fx package is more flexible and powerful, however, because extended color objects are used to construct other extended color objects. The following example shows how you can use multiple extended color objects with an extended graphics object to draw some simple effects.

 // Draw the same oval as before, but this time, use an imported
 // GIF image as a color. First, create an extended graphics object.
fxGraf = FxGraphics.getExtendedGraphics(Graphics gOrig);

// Create an FxTexture object that uses 
// a RedImage.gif as a base.
FxTexture fxTex1 = new FxTexture(myRedImage, FxTexture.STRETCH_NONE,
                                 0, 0, -1, -1, false, 255, 0, 0);

// Create an FxPen 8 pixels wide, that uses 
// the FxTexture as a drawing color.
FxPen widePen = new FxPen(8, fxTex1);

// Set the drawing color used in the graphics context.
// The FxPen is selected into the context the same way 
// a Color is selected.
fxGraf.setColor(widePen);

// Now draw the same oval as before with a pen 8 pixels wide.
// The pen uses a .gif image to draw, or if the image fails to draw,
// the color (255, 0, 0) is used by default.
fxGraf.drawOval(2, 2, 60, 40);

The extended graphics object and extended objects selected as its color and font use callback methods to draw the effects. This enables you to use the same familiar API to draw more powerful graphics.

Callback Methods

In the previous example, both FxPen and FxTexture objects are used instead of a Color object, but the method call

g.drawOval(x, y, width, height);

remains the same. The callback methods are called from the graphics object when it performs a drawing operation, and its selected Color object is an instance of a class derived from FxFill or FxFont. In this case, the FxGraphics object called upon the FxPen.drawOvalCallback method to draw the oval.

All of the callback methods (fillArcCallback, drawLineCallback, and so on) included in the Microsoft com.ms.fx package for Java are used only by the graphics object, not the application. The documentation for these callback methods is included for Java developers who want to extend these objects.

FxSystemFont, FxSystemIcon, and Texture and Image Class Factories

The com.ms.fx package includes a number of classes that provide consistent, cross-platform system images, icons, and access to system fonts.

The FxSystemFont class handles fonts that are reserved for graphical user-interface components such as dialog boxes and menus. These fonts are system-specific, and on platforms other than Microsoft® Win32™, the font retrieved will be a predefined, standard font. The class provides methods to retrieve specific reserved fonts, such as getMessageBoxFont and getSmallCaptionFont. FxSystemFont also provides methods, such as getAttributeList and getStyleVal, to determine attributes associated with a particular system font on a given platform.

The FxSystemIcon class provides a set of standard .gif images that are used in cross-platform dialog boxes. Four images are provided with the com.ms.fx package.

The texture and image class factories, including the FxComponentTexture and FxStateConfigurableUIImage classes, provide sets of component images and textures for AFC controls. These classes are state dependent; the sets of images are provided for corresponding component states.

For example, the FxComponentImage class provides a set of state-dependent images for each of the included component images (the arrow images on scroll bars, check box images, and so on). Not all states are valid for different components, so the class only provides images for states that are valid for the selected component.

The FxStateConfigurableImage class enables developers to create their own state-dependent image factories.

Internationalization Support

The com.ms.fx package provides support for formatted text in any language, characters not defined in the Unicode standard, text rotation, vertical writing, Input Method Editors (IMEs), and other internationalization (i18n) features.

The FxFormattedText class, a formatted text buffer class, is one of the core Fx classes. It provides methods that enable the user to specify text direction, locale, text alignment, word wrap, mnemonic characters, kerning, password characters, as well as normal buffer operations that are inherited from the FxText class. An FxFormattedText object is created from either a String or character array of Unicode characters.

Text rotation and vertical writing are both supported through the FxFormattedText and FxGraphics classes. In particular, text rotation is supported with the FxGraphics.drawString(String str, int x, int y, int a) method. Vertical writing is supported by the setTextDirection and setLocale methods.

The FxCaret class provides a cross-platform caret, similar to the flashing caret in the Microsoft Windows® Notepad application. FxCaret is also used in the com.ms.util.InputMethod package to support Java Input Method Editor composition windows. The Java application uses InputMethodListener.setVisibleComponent to specify where the IME is shown, and the Java application can use InputMethodListener.setPos to set the position of the composition window. The IME is attached to an FxCaret object, and every time the FxCaret is shown or moved, the FxCaret object calls setPos to set the position of the IME composition window.

JDK 1.0.2 and 1.1 Support

The Microsoft Application Foundation Classes are designed not only to be a cross-platform solution, but to be both JDK 1.1 and JDK 1.0.2 compatible. The com.ms.fx package provides graphics support for both 1.1 and 1.0.2 VMs.

One limitation of the JDK 1.0.2 is that the java.awt.Color class is declared final (in JDK 1.1 it is not). Many of the classes in the com.ms.fx package extend the java.awt.Color class in JDK 1.1, but can't extend Color in 1.0.2. In order to provide the functionality of the com.ms.fx package and the AFC for 1.0.2 VMs, the com.ms.fx extended color classes are derived from the com.ms.fx.BaseColor class. The BaseColor class is a public class, but it is never used directly in applets or applications. The following diagram shows the extended color class hierarchy using both JDK 1.0.2 and 1.1 color models:

The BaseColor class is derived directly from Object in 1.0.2 because java.awt.Color is declared final. It provides the same basic functionality, so there are really no effective differences using an FxColor in 1.0.2.

For graphics-related code to compile and run under both JDK 1.0.2 and JDK 1.1 Virtual Machines, you need to design your code with the following limitations in mind.

Extended Color Limitations Using 1.0.2	The com.ms.ui package does not support the setBackground(FxColor) operation when running on JDK 1.0.2-based VMs. You can work around this limitation by overriding the update() method and selecting the color into the graphics object before clearing the background and calling paint().
	You can't set textures as the background colors of components under 1.0.2 VMs. You can implement this by overriding the update method in extended color classes, as the following example shows. public class MyCanvas { FxColor myTexture; public void update(FxGraphics g) { g.setColor(myTexture); g.fillRect(0, 0, getSize().width, getSize().height); paint(g); } }
Compiling Extended Colors for JDK 1.0.2 VMs	The extended color classes are easy to use and select into a graphics context when writing JDK 1.1 compliant code with the AFC libraries. But because the java.awt.Color+ class is final in 1.0.2, some graphics-related AFC code will not compile in 1.0.2. For example, if you were writing an application that uses an FxPen to draw wide lines, you might create the FxPen object and select it into a graphics context as shown in the following example. FxPen pen1 = new FxPen(5, 255, 0, 124); // Set the color of the graphics object. fxg.setColor(pen1); This does not compile under 1.0.2 because FxColor (and therefore FxPen) is derived from Object, not from Color. Any time you want to use extended color objects under JDK 1.0.2, you must select them into a graphics context using the the FxColor.getColor method. FxPen pen2 = new FxPen(5, 124, 255, 0); FxTexture mytex = new FxTexture(someImage, FxTexture.STRETCH_NONE, 0, 0, -1, -1, false, 0, 10, 70); fxg.setColor(FxColor.getColor(pen2)); panel.setForeground(mytex.getColor());

Integration

Integration with the com.ms.ui Package

The classes in the com.ms.fx are used extensively throughout the com.ms.ui (UI) package. The following list briefly discusses how some of the Fx classes are used throughout UI.

FxColor	The FxColor class is used in UI classes such as UIColorDialog, UIComponent and UIScroll to set text background colors and shading and to retrieve colors that are lighter or darker than the original colors for edges and effects.
FxSystemFont	The FxSystemFont class is used in many UI classes to retrieve message box and menu fonts, with the getMessageBoxFont and getMenuFont methods.
FxSystemIcon	The FxSystemIcon class is used in the UIMessageBox class to provide system images for message boxes.
FxToolkit	The FxToolkit class is used extensively throughout both the com.ms.fx and com.ms.ui packages. It provides platform-independent methods for retrieving low-level information. For example, controls can use reserved colors and platform-specific metrics using the getSystemColor and getSystemMetric methods. The system interface returns a platform-independent graphics object that takes care of differences in the various platforms. The Dialog.setModal() method (which is not available within JDK 1.0.2) is set using the FxToolkit.getSystemInterface().setDialog() method. The FxToolkit class is used in the UIDrawText, UIEdit, UIPropertyPage, and UIMenuItem classes.
FxComponentImage	The FxComponentImage class is used in UI classes such as UIChoice, UIExpandButton, and UIRadioButton to provide a set of images for the component's possible states.
FxFormattedText	The FxFormattedText class is used in UIDrawText to perform operations on formatted text buffers.