Class FxTexture

public class FxTexture extends FxFill implements ImageObserver
{
  // Fields
  public final static int DRAW_BL;
  public final static int DRAW_BOTTOM;
  public final static int DRAW_BR;
  public final static int DRAW_CENTER;
  public final static int DRAW_LEFT;
  public final static int DRAW_RIGHT;
  public final static int DRAW_TL;
  public final static int DRAW_TOP;
  public final static int DRAW_TR;
  public final static int REPEAT_PIN;
  public final static int SNAP_EDGES;
  public final static int STRETCH_ALL;
  public final static int STRETCH_MIDDLE;
  public final static int STRETCH_NONE;
  public final static int STRETCH_OUTER;

  // Constructors
  public FxTexture(Image i);
  public FxTexture(Image i, int s, int l, int t, int r, int b,
        boolean p, int red, int green, int blue);
  public FxTexture(Image i, int s, int l, int t, int r, int b,
        boolean p, Color base);
  public FxTexture(Image i, int s, int l, int t, int r, int b,
        boolean p, FxFill base);
  public FxTexture(Image i, int s, int l, int t, int r, int b,
        boolean p);

  // Methods
  public boolean drawScanLinesCallback(FxGraphics g,
        boolean xChanging, int points[], int offset, int nPoints);
  public boolean fillArcCallback(FxGraphics g, int x, int y,
        int width, int height, int startAngle, int arcAngle);
  public boolean fillOvalCallback(FxGraphics g, int x, int y,
        int width, int height);
  public boolean fillPolygonCallback(FxGraphics g, int xPoints[],
        int yPoints[], int nPoints);
  public boolean fillRectCallback(FxGraphics g, int xStart,
        int yStart, int width, int height);
  public boolean fillRoundRectCallback(FxGraphics g, int x, int y,
        int width, int height, int arcWidth, int arcHeight);
  public int getBottomAxis();
  public Image getImage();
  public Rectangle getInner();
  public int getLeftAxis();
  public boolean getPinOrigin();
  public int getRightAxis();
  public boolean getSnapDraw();
  public int getStretch();
  public int getTopAxis();
  public int getUpdatedAreasMask();
  public boolean imageUpdate(Image img, int infoflags, int x,
        int y, int width, int height);
  public void setAxis(int l, int t, int r, int b);
  public void setPinOrigin(boolean b);
  public void setSnapDraw(boolean b);
  public void setStretch(int s);
  public void setUpdateCallback(IFxTextureUpdate tu);
  public void setUpdatedAreasMask(int mask);
  public Dimension size();
}

This class uses images, including .gif and .jpeg file formats, to fill shapes and draw graphics effects. An FxTexture may be used for both foreground drawing colors and background colors.

To select an image as a background, use the Component.setBackground(Color c) or the UIComponent.setBackground(Color color) method and pass the FxTexture as the Color object. If the image cannot be drawn, a default RGB color, Color, or FxFill will be used instead.

To select an image as a foreground color, select the FxTexture object into a drawing object, such as FxPen, FxRubberPen, or FxBrushPen. A graphics object will perform the same operations with FxTexture or FxPen that it does with a Color object.

Note The callback methods used in this and other classes that are derived from FxColor and FxFill are used internally only; they are not for use directly by applications. For more information on the use of callback methods in the com.ms.fx package, see the overview information at the beginning of this article.

The following example shows you how to construct several different FxTexture objects.

// In many cases, you will use an FxTexture as a simple background 
// fill. In these cases, where you do not want the image stretched in
// any way, you can use the following constructs.

fxt = new FxTexture(img[TEXTURE], FxTexture.STRETCH_NONE, 
                    0,0,-1,-1, false, Color.red);

// The first parameter is an imported image to base the texture on. The 
// second parameter handles image stretching. When you want the image
// drawn normally, use STRETCH_NONE. If you want the image stretched
// across a surface, you can use either STRETCH_MIDDLE, STRETCH_OUTER,
// or STRETCH_ALL. The third and fourth parameters set the starting
// location of the image relative to the drawing canvas (in this case, the
// location is point 0,0). The fifth and sixth parameters set the width and height
// of the image drawn on the canvas. Set these values to -1 to specify that
// the image is drawn to its normal dimension (if you use STRETCH_NONE, you
// will always set these to -1). Set the seventh parameter to true if 
// you want a texture pinned. The final parameter sets a color to use
// in case the image fails to draw. This can be a Color, a set of
// (r,g,b) values, or an FxFill object.

// In some cases, you may want to use the default backup color when creating
// an FxTexture. The default color is white. 

fxt = new FxTexture(img[TEXTURE], FxTexture.STRETCH_NONE,
                    0,0,-1,-1, false);

// FxTexture objects can be selected into a graphics context
// the same way a Color is selected. This makes it easy to
// use textures as backgrounds for any component. 

setBackground(new FxTexture(img[TEXTURE], FxTexture.STRETCH_NONE, 
                             0,0,-1,-1,false, 100, 100, 100));

// In cases where you want an image stretched across a surface, you 
// can force the texture to be drawn in a specified pixel dimension, 
// regardless of what the original dimension of the image is. In the 
// following example, the original image is stretched to 300 pixels
// wide by 100 pixels high.

fxt = new FxTexture(img[TEXTURE], FxTexture.STRETCH_ALL,
                    0,0,300,100, false, Color.cyan);

An FxGraphics object draws supported primitives with the same method calls you use when drawing with Color objects.

// Draw primitives using an FxTexture object.

fxGraf.setColor(fxt);

fxGraf.fillOval(varX, varY, variableWidth, variableHeight);
// or
fxGraf.fillPolygon(xPntArray, yPntArray, numPts);

The FxTexture class supports drawing partial textures according to a nine-rectangle grid. The following example shows how you can draw partial textures using the setUpdatedAreasMask method.

// Set an IFxTextureUpdate object for the texture. This
// interface supports the textureUpdated method.

fxt.setUpdateCallback(ifxtu);

// Set the visible areas drawing mask for the texture. This is a mask that
// defines which areas of the texture are drawn.

fxt.setUpdatedAreasMask(FxTexture.DRAW_TL + FxTexture.DRAW_TR + 
                        FxTexture.DRAW_BL + FxTexture.DRAW_BR);

BaseColor
  |
  +--FxColor
    |
    +--FxFill
      |
      +--FxTexture

Constructors

FxTexture

public FxTexture(Image i);

Constructs a texture by using a given image. If the image cannot be drawn, the default color (0,0,0) is used instead.

Parameter	Description
i	The image object to use as the base of the texture.

FxTexture

public FxTexture(Image i, int s, int l, int t, int r, int b, boolean p, int
        red, int green, int blue);

Constructs a texture with a specific default color.

Parameter	Description
i	The image object to use as the basis of the texture.
s	The value that handles image stretching. This value may be one of the following: STRETCH_NONE STRETCH_MIDDLE STRETCH_OUTER STRETCH_ALL
l	The left boundary.
t	The top boundary.
r	The right boundary. Set this value to -1 if the right boundary is the full width of the image.
b	The bottom boundary. Set this value to -1 if the bottom boundary is the full height of the image.
p	Set this value to true if the image should be pinned.
red	The amount of red in the color. The color (r,g,b) is used in the event that the texture cannot be drawn by using the given image.
green	The amount of green in the color.
blue	The amount of blue in the color.

FxTexture

public FxTexture(Image i, int s, int l, int t, int r, int b, boolean p,
        Color base);

Constructs a texture with a specific default Color object.

Parameter	Description
i	The image object to use as the basis of the texture.
s	The value that handles image stretching. This value may be one of the following: STRETCH_NONE STRETCH_MIDDLE STRETCH_OUTER STRETCH_ALL
l	The left boundary.
t	The top boundary.
r	The right boundary. Set this value to -1 if the right boundary is the full width of the image.
b	The bottom boundary. Set this value to -1 if the bottom boundary is the full height of the image.
p	Set this value to true if the image should be pinned.
base	The Color object to use as the default should the texture fail to draw with the given image.

FxTexture

public FxTexture(Image i, int s, int l, int t, int r, int b, boolean p,
        FxFill base);

Constructs a texture by using a given image. In the event the image cannot be drawn, an FxFill object is used instead.

Parameter	Description
i	The image object.
s	The value that handles image stretching. This value may be one of the following: STRETCH_NONE STRETCH_MIDDLE STRETCH_OUTER STRETCH_ALL
l	The left boundary.
t	The top boundary.
r	The right boundary. Set this value to -1 if the right boundary is the full width of the image.
b	The bottom boundary. Set this value to -1 if the bottom boundary is the full height of the image.
p	Set this value to true if the image is pinned.
base	The FxFill object to use as the base should the texture fail to draw using the given image.

FxTexture

public FxTexture(Image i, int s, int l, int t, int r, int b, boolean p);

Constructs a texture using an image as a base for the texture. In the event the image cannot be drawn, the default color (0,0,0) is used instead.

Parameter	Description
i	The image object.
s	The value that handles image stretching. This may be one of the following: STRETCH_NONE STRETCH_MIDDLE STRETCH_OUTER STRETCH_ALL
l	The left boundary.
t	The top boundary.
r	The right boundary. Set this value to -1 if the right boundary is the full width of the image.
b	The bottom boundary. Set this value to -1 if the bottom boundary is the full height of the image.
p	Set this value to true if the image should be pinned.

Methods

drawScanLinesCallback

public boolean drawScanLinesCallback(FxGraphics g, boolean xChanging,
        int points[], int offset, int nPoints);

Draws scan lines by using an image as a fill color when called by an FxGraphics object.

Note This method is called by FxGraphics if drawScanLines is called and if an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns true if successful; otherwise, returns false.

Parameter	Description
g	The graphics object used to draw the scan lines.
xChanging	The direction the line should be drawn (horizontally or vertically).
points	An array of points (expressed in x,y coordinates).
offset	The offset to use.
nPoints	The number of points in the array.

Overrides:

drawScanLinesCallback(FxGraphics,boolean,int[],int,int) in FxFill.

See Also: com.ms.fx.FxGraphics.drawScanLines, com.ms.fx.FxFill.drawScanLinesCallback

fillArcCallback

public boolean fillArcCallback(FxGraphics g, int x, int y, int width,
        int height, int startAngle, int arcAngle);

Draws a filled arc centered on the given (x,y) coordinates by using an image as a fill color when called by an FxGraphics object.

Note This method is called by FxGraphics if fillArc is called and an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns false.

Parameter	Description
g	The graphics object used to draw the filled arc.
x	The x coordinate of the arc's origin.
y	The y coordinate of the arc's origin.
width	The width of the arc (in pixels).
height	The height of the arc (in pixels).
startAngle	The starting angle of the arc.
arcAngle	The angle of the arc.

Overrides:

fillArcCallback(FxGraphics,int,int,int,int,int,int) in FxFill.

See Also: java.awt.Graphics.fillArc, com.ms.fx.FxFill.fillArcCallback

fillOvalCallback

public boolean fillOvalCallback(FxGraphics g, int x, int y, int width,
        int height);

Draws a filled oval by using an image as a fill color when called by an FxGraphics object.

Note This method is called by FxGraphics if fillOval is called and if an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns false.

Parameter	Description
g	The graphics object used to draw the filled oval.
x	The upper-left x coordinate of the oval's bounding rectangle.
y	The upper-left y coordinate of the oval's bounding rectangle.
width	The width of the oval (in pixels).
height	The height of the oval (in pixels).

Overrides:

fillOvalCallback(FxGraphics,int,int,int,int) in FxFill.

See Also: java.awt.Graphics.fillOval, com.ms.fx.FxFill.fillOvalCallback

fillPolygonCallback

public boolean fillPolygonCallback(FxGraphics g, int xPoints[],
        int yPoints[], int nPoints);

Draws a filled polygon by using an image as a fill color when called by an FxGraphics object.

Note Called by FxGraphics if fillPolygon is called and if an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns false.

Parameter	Description
g	The graphics object to use to draw the filled polygon.
xPoints	An array containing the polygon x coordinates.
yPoints	An array containing the polygon y coordinates.
nPoints	The number of points in the polygon.

Overrides:

fillPolygonCallback(FxGraphics,int[],int[],int) in FxFill.

See Also: java.awt.Graphics.fillPolygon, com.ms.fx.FxFill.fillPolygonCallback

fillRectCallback

public boolean fillRectCallback(FxGraphics g, int xStart, int yStart,
        int width, int height);

Draws a filled rectangle by using an image as a fill color when called by an FxGraphics object.

Note This method is called by FxGraphics if fillRect is called and if an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns true if successful; otherwise, returns false.

Parameter	Description
g	The graphics object used to draw the filled rectangle.
xStart	The upper-left x coordinate of the rectangle.
yStart	The upper-left y coordinate of the rectangle.
width	The width of the rectangle (in pixels).
height	The height of the rectangle (in pixels).

Overrides:

fillRectCallback(FxGraphics,int,int,int,int) in FxFill.

See Also: java.awt.Graphics.fillRect, com.ms.fx.FxFill.fillRectCallback

fillRoundRectCallback

public boolean fillRoundRectCallback(FxGraphics g, int x, int y, int width,
        int height, int arcWidth, int arcHeight);

Draws a filled rectangle with rounded edges by using an image as a fill color when called by an FxGraphics object.

Note This method is called by FxGraphics if fillRoundRect is called and an FxTexture object is the selected color. The callback methods are used internally and are not intended to be called by applications. They are made public so that derived classes can extend the callback functionality.

Return Value:

Returns false.

Parameter	Description
g	The graphics object.
x	The upper-left x coordinate of the rectangle.
y	The upper-left y coordinate of the rectangle.
width	The width of the rectangle (in pixels).
height	The height of the rectangle (in pixels).
arcWidth	The arc width of the rectangle's rounded edges.
arcHeight	The arc height of the rectangle's rounded edges.

Overrides:

fillRoundRectCallback(FxGraphics,int,int,int,int,int,int) in FxFill.

See Also: java.awt.Graphics.fillRoundRect, com.ms.fx.FxFill.fillRoundRectCallback

getBottomAxis

public int getBottomAxis();

Retrieves the bottom bound for the stretch and repeat factors.

Return Value:

Returns the bottom bound for the stretch and repeat factors.

getImage

public Image getImage();

Retrieves the image being used by the FxTexture object.

Return Value:

Returns the Image. If no image is currently associated with the FxTexture object, the method returns null.

getInner

public Rectangle getInner();

Retrieves the bounds of the inner Rectangle of the texture.

Return Value:

Returns the inner Rectangle of the texture.

getLeftAxis

public int getLeftAxis();

Retrieves the left bound for the stretch and repeat factors.

Return Value:

Returns the left bound for the stretch and repeat factors.

getPinOrigin

public boolean getPinOrigin();

Checks whether the image is pinned.

Return Value:

Returns true if the image is pinned; otherwise, returns false.

getRightAxis

public int getRightAxis();

Retrieves the right bound for the stretch and repeat factors.

Return Value:

Returns the right bound for the stretch and repeat factors.

getSnapDraw

public boolean getSnapDraw();

Checks whether partial images should be repeated.

Return Value:

Returns true if partial images should be repeated; otherwise, returns false.

getStretch

public int getStretch();

Checks if the image is stretched across the surface rather than being repeated.

Return Value:

Returns a value that determines if the image is stretched.

getTopAxis

public int getTopAxis();

Retrieves the top bound for the stretch and repeat factors.

Return Value:

Returns the top bound for the stretch and repeat factors.

getUpdatedAreasMask

public int getUpdatedAreasMask();

Retrieves a drawing mask for the currently visible areas.

Return Value:

Returns a mask for the currently visible areas.

See Also: setUpdatedAreasMask

imageUpdate

public boolean imageUpdate(Image img, int infoflags, int x, int y,
        int width, int height);

Determines when an image can be drawn. This method is called when information requested about the image becomes available.

Return Value:

Returns true if the image can be drawn; otherwise, returns false.

Parameter	Description
img	The image object.
infoflags	The flags controlling the method. Set this value to zero to use the default values for the ImageObserver object.
x	The x coordinate of the image's starting point.
y	The y coordinate of the image's starting point.
width	The width of the image (in pixels).
height	The height of the image (in pixels).

See Also: java.awt.image.ImageObserver

setAxis

public void setAxis(int l, int t, int r, int b);

Sets the bounds for the stretch and repeat factors.

Return Value:

No return value.

Parameter	Description
l	The left bound.
t	The top bound.
r	The right bound.
b	The bottom bound.

setPinOrigin

public void setPinOrigin(boolean b);

Sets whether the image should be pinned.

Return Value:

No return value.

Parameter	Description
b	Set to true if the image should be pinned.

setSnapDraw

public void setSnapDraw(boolean b);

Determines whether partial images should be repeated.

Return Value:

No return value.

Parameter	Description
b	Set to true if partial images should be repeated across a surface.

setStretch

public void setStretch(int s);

Sets the stretch or the repeat value.

Return Value:

No return value.

Parameter	Description
s	The value that determines if the image is stretched or repeated.

setUpdateCallback

public void setUpdateCallback(IFxTextureUpdate tu);

Sets an IFxTextureUpdate callback instance. The IFxTextureUpdate.textureUpdated callback method is called with the nine UIGridLayout or UIGridBagLayout grid areas after every drawing operation. If one of the grid's lines is not set, the corresponding rectangles will be removed from the Rectangle array.

Return Value:

No return value.

Parameter	Description
tu	The IFxTextureUpdate callback interface to set for the texture.

setUpdatedAreasMask

public void setUpdatedAreasMask(int mask);

Sets a mask for the currently visible areas. You can set this mask so that only certain areas of an FxTexture are drawn.

Return Value:

No return value.

Parameter	Description
mask	The mask for the visible areas. This can be one or a combination of the following masks. DRAW_TL DRAW_TOP DRAW_TR DRAW_LEFT DRAW_CENTER DRAW_RIGHT DRAW_BL DRAW_BOTTOM DRAW_TR

See Also: getUpdateAreasMask

size

public Dimension size();

Retrieves the size of the Image that is associated with the texture.

Return Value:

Returns the Dimension of the image.

Fields

DRAW_BL

The value used in setVisibleArea to draw the lower-left corner of a grid.

DRAW_BOTTOM

The value used in setVisibleArea to draw the bottom row of a grid.

DRAW_BR

The value used in setVisibleArea to draw the lower-right corner of a grid.

DRAW_CENTER

The value used in setVisibleArea to draw the center of a grid.

DRAW_LEFT

The value used in setVisibleArea to draw the left bar of a grid.

DRAW_RIGHT

The value used in setVisibleArea to draw the right bar of a grid.

DRAW_TL

The value used in setVisibleArea to draw the upper-left corner of a grid.

DRAW_TOP

The value used in setVisibleArea to draw the top row of a grid.

DRAW_TR

The value used in setVisibleArea to draw the upper-right corner of a grid.

REPEAT_PIN

When repeating, tie the bitmap to the logical corner (0,0) instead of the upper-left corner of the requested area.

SNAP_EDGES

When repeating, if the draw operation results in a partial drawing of an edge, shrink the image to fix exactly.

STRETCH_ALL

When filling onto a surface, the texture is stretched to fit.

STRETCH_MIDDLE

When filling onto a surface, only the middle area is stretched to fit. The border areas will retain their original dimensions.

STRETCH_NONE

No stretching is done to fill the required area on the target surface. The image contained within the texture is repeated to fill the space. If this flag is set, any guidelines will be ignored.

STRETCH_OUTER

When filling onto a surface, only the middle area is repeated to fit. The border areas will be stretched to fit the surface.