jcontrol.graphics
Interface XGraphics

All Superinterfaces:

Graphics

All Known Implementing Classes:

BufferGraphics, XDisplay

public interface XGraphics
extends Graphics

The XGraphics interface offers a variety of enhancements over the Graphics interface. Apart from offering more drawing methods (such as for drawing polygons or ovals), it has two fundamental changes:

• XGraphics classes support clipping and coordinate translation,
• and multiple instances are explicitly allowed.

Clipping and translation allows to reduce the area in the framebuffer that is possible to draw on. Furthermore, through translation, it's possible to define, in a very limited sense, local coordinate systems, simply by moving the translation point to the desired coordinate origin. All drawing methods of XGraphics classes will add this origin position to the locations specified in their calls.
For example, setting the translation point to (0,0) and then drawing an image to location (100,100) has the same effect as setting the translation point to (100,100) and drawing the image to location (0,0).
This comes in handy in creating user interfaces, where before drawing a widget the translation point is adjusted accordingly. This allows the implementation of the widget's graphical appearance to imply that the point (0,0) lies in it's upper left corner, thus making the implementation independent (and more readable) from the widget's position.
By defining a clipping rectangle before drawing, it's also possible to limit the area a widget can draw in. This can prevent from drawing outside the area, that a widget actually covers.

While the possibility of having multiple instances is not a requirement for Graphics objects, it is one for XGraphics objects. In a multi threading environment, this feature can be used to have more than one thread drawing on a display simulatously without having to take care of the synchronization in the main application.

Important note: When setting drawing and background colors, it's important to know that the color format is ARGB, which means that 8 bits are used for defining a color's translucency, where 0 means that a color is fully transparent (invisible) and 255 means that a color is opaque. When simply using RGB values in setColor or setBackground, like 0xFF0000 for red, the translucency value is 0 always, which means that the color is invisible. The right way to define an opaque color is to supply a 0xFF in the value's high byte, e.g. 0xFFFF0000 for red or 0xFF00FFFF for cyan.

Field Summary

static int	ANCHOR_BASELINE anchor for aligning text
static int	ANCHOR_BOTTOM anchor for aligning text and images
static int	ANCHOR_HCENTER anchor for aligning text and images
static int	ANCHOR_LEFT anchor for aligning text and images
static int	ANCHOR_RIGHT anchor for aligning text and images
static int	ANCHOR_TOP anchor for aligning text and images
static int	ANCHOR_VCENTER anchor for aligning text and images
static int	DRAWMODE_AND drawmode: logical AND
static int	DRAWMODE_INVERSE drawmode: inverse (use background color for drawing and foreground color for clearing)
static int	DRAWMODE_MASK drawmode: masked (draw masked text and JCIF1 images (i.e. background doesn't get cleared)
static int	DRAWMODE_NORMAL drawmode: replace pixels
static int	DRAWMODE_OR drawmode: logical OR
static int	DRAWMODE_XOR drawmode: logical XOR
static int	MAX_BRIGHTNESS maximum backlight brightness
static int	MAX_CONTRAST maximum backlight contrast
static int	MIN_BRIGHTNESS minimum backlight brightness
static int	MIN_CONTRAST minimum backlight contrast
static int	STROKEMODE_DOTTED strokemode: draw dotted (or broken) lines (rects, ovals, etc.)
static int	STROKEMODE_SOLID strokemode: draw solid lines (rects, ovals, etc.)

Fields inherited from interface jcontrol.io.Graphics

AND, INVERSE, NORMAL, OR, XOR

Method Summary

boolean	clipRect(int x, int y, int width, int height) Downsizes the current clipping rectangle by intersection with the given rectangle.
XGraphics	cloneXGraphics() Creates a clone of this XGraphics object that has the same settings as this one, but acts independently.
void	copyArea(int x, int y, int width, int height, int dx, int dy) Copies an area within the framebuffer.
void	drawArc(int x, int y, int width, int height, int startAngle, int arcAngle) Draws an elliptic arc.
int	drawChar(char c, int x, int y) Draws a single character with the currently set font.
int	drawChar(char c, int x, int y, int anchor) Draws a single character with the currently set font.
void	drawImage(Object drawable, int x, int y, int anchor) Draws an image.
void	drawOval(int x, int y, int width, int height) Draws an ellipse.
void	drawPolygon(int[] xPoints, int[] yPoints, int nPoints) Draws a closed polyline.
void	drawPolyline(int[] xPoints, int[] yPoints, int nPoints) Draws a polyline.
void	drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) Draws a rounded rectangle.
void	drawString(String s, int x, int y, int anchor) Draws a text string with the currently set font.
void	fillArc(int x, int y, int width, int height, int startAngle, int arcAngle) Draws a filled elliptic arc, which is similar to a pie charts element.
void	fillOval(int x, int y, int width, int height) Draws a filled ellipse.
void	fillPolygon(int[] xPoints, int[] yPoints, int nPoints) Draws a polygon.
void	fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight) Draws a filled rounded rectangle.
int	getBackground() Returns the ARGB value of the current background color.
int	getClipHeight() Returns the current clipping rectangle's height.
int	getClipWidth() Returns the current clipping rectangle's width.
int	getClipX() Returns the current clipping rectangle's x-location relatively to the translation point.
int	getClipY() Returns the current clipping rectangle's y-location relatively to the translation point.
int	getColor() Returns the ARGB value of the current drawing color.
Object	getFont() Returns the currently set font.
int	getStrokeMode() Returns the current stroke mode.
int	getTranslateX() Get's the translation point's x-location.
int	getTranslateY() Get's the translation point's y-location.
boolean	isClipRectEmpty() Checks, if the current clipping rectangle is empty (i.e. doesn't cover any pixel).
boolean	isOverlapping(int x, int y, int width, int height) Checks, if the given rectangle overlaps (or - mathematically spoken - intersects) with the current clipping rectangle.
void	scroll(int dx, int dy) Scrolls the area specified by the clipping rectangle.
void	setBackground(Color c) Sets the background color.
void	setBackground(int c) Sets the background color.
void	setClip(int x, int y, int width, int height) Sets the clipping rectangle.
void	setColor(Color c) Sets the drawing color.
void	setColor(int c) Sets the drawing color.
void	setStrokeMode(int mode) Sets the stroke mode.
void	swapColors() Swaps drawing and background color.
void	translate(int dx, int dy) Moves the translation (origin) point.

Methods inherited from interface jcontrol.io.Graphics

clearRect, drawImage, drawImage, drawLine, drawRect, drawString, drawString, fillRect, getDrawMode, getFontHeight, getPixel, getTextWidth, setDrawMode, setFont, setPixel

Field Detail

DRAWMODE_NORMAL

static final int DRAWMODE_NORMAL

drawmode: replace pixels

See Also:

Constant Field Values

DRAWMODE_AND

static final int DRAWMODE_AND

drawmode: logical AND

See Also:

Constant Field Values

DRAWMODE_OR

static final int DRAWMODE_OR

drawmode: logical OR

See Also:

Constant Field Values

DRAWMODE_XOR

static final int DRAWMODE_XOR

drawmode: logical XOR

See Also:

Constant Field Values

DRAWMODE_INVERSE

static final int DRAWMODE_INVERSE

drawmode: inverse (use background color for drawing and foreground color for clearing)

See Also:

Constant Field Values

DRAWMODE_MASK

static final int DRAWMODE_MASK

drawmode: masked (draw masked text and JCIF1 images (i.e. background doesn't get cleared)

See Also:

Constant Field Values

ANCHOR_TOP

static final int ANCHOR_TOP

anchor for aligning text and images

See Also:

Constant Field Values

ANCHOR_BOTTOM

static final int ANCHOR_BOTTOM

anchor for aligning text and images

See Also:

Constant Field Values

ANCHOR_VCENTER

static final int ANCHOR_VCENTER

anchor for aligning text and images

See Also:

Constant Field Values

ANCHOR_BASELINE

static final int ANCHOR_BASELINE

anchor for aligning text

See Also:

Constant Field Values

ANCHOR_LEFT

static final int ANCHOR_LEFT

anchor for aligning text and images

See Also:

Constant Field Values

ANCHOR_RIGHT

static final int ANCHOR_RIGHT

anchor for aligning text and images

See Also:

Constant Field Values

ANCHOR_HCENTER

static final int ANCHOR_HCENTER

anchor for aligning text and images

See Also:

Constant Field Values

STROKEMODE_SOLID

static final int STROKEMODE_SOLID

strokemode: draw solid lines (rects, ovals, etc.)

See Also:

Constant Field Values

STROKEMODE_DOTTED

static final int STROKEMODE_DOTTED

strokemode: draw dotted (or broken) lines (rects, ovals, etc.)

See Also:

Constant Field Values

MIN_BRIGHTNESS

static final int MIN_BRIGHTNESS

minimum backlight brightness

See Also:

Constant Field Values

MAX_BRIGHTNESS

static final int MAX_BRIGHTNESS

maximum backlight brightness

See Also:

Constant Field Values

MIN_CONTRAST

static final int MIN_CONTRAST

minimum backlight contrast

See Also:

Constant Field Values

MAX_CONTRAST

static final int MAX_CONTRAST

maximum backlight contrast

See Also:

Constant Field Values

Method Detail

setStrokeMode

void setStrokeMode(int mode)

Sets the stroke mode.

Parameters:

stroke - mode (STROKEMODE_SOLID or STROKEMODE_DOTTED)

getStrokeMode

int getStrokeMode()

Returns the current stroke mode.

Returns:

current strokemode

scroll

void scroll(int dx,
            int dy)

Scrolls the area specified by the clipping rectangle. Scrolling is cyclic, i.e. parts of the image that get scrolled out of the clipping rectangle reappear on the other side.

Parameters:

dx - horizontal scrolling offset

dy - vertical scrolling offset

drawArc

void drawArc(int x,
             int y,
             int width,
             int height,
             int startAngle,
             int arcAngle)

Draws an elliptic arc.

Parameters:

x - x-location of the underlying ellipse

y - y-location of the underlying ellipse

width - width of the underlying ellipse

height - height of the underlying ellipse

startAngle - angle from where to start drawing (in degrees)

arcAngle - angle along which the arc has to be drawn (in degrees)

fillArc

void fillArc(int x,
             int y,
             int width,
             int height,
             int startAngle,
             int arcAngle)

Draws a filled elliptic arc, which is similar to a pie charts element.

Parameters:

x - x-location of the underlying ellipse

y - y-location of the underlying ellipse

width - width of the underlying ellipse

height - height of the underlying ellipse

startAngle - angle from where to start drawing (in degrees)

arcAngle - angle along which the arc has to be drawn (in degrees)

drawRoundRect

void drawRoundRect(int x,
                   int y,
                   int width,
                   int height,
                   int arcWidth,
                   int arcHeight)

Draws a rounded rectangle.

Parameters:

x - x-location

y - y-location

width - width

height - height

arcWidth -

arcHeight -

fillRoundRect

void fillRoundRect(int x,
                   int y,
                   int width,
                   int height,
                   int arcWidth,
                   int arcHeight)

Draws a filled rounded rectangle.

Parameters:

x - x-location

y - y-location

width - width

height - height

arcWidth -

arcHeight -

drawPolygon

void drawPolygon(int[] xPoints,
                 int[] yPoints,
                 int nPoints)

Draws a closed polyline. Closed means that a line is drawn between the first and the last point defining the polyline.

Parameters:

xPoints - x-locations of the polyline's points

yPoints - y-locations of the polyline's points

nPoints - number of points

See Also:

drawPolyline(int[], int[], int)

drawPolyline

void drawPolyline(int[] xPoints,
                  int[] yPoints,
                  int nPoints)

Draws a polyline.

Parameters:

xPoints - x-locations of the polyline's points

yPoints - y-locations of the polyline's points

nPoints - number of points

See Also:

drawPolygon(int[], int[], int)

fillPolygon

void fillPolygon(int[] xPoints,
                 int[] yPoints,
                 int nPoints)

Draws a polygon.

Parameters:

xPoints - x-locations of the polygon's points

yPoints - y-locations of the polygon's points

nPoints - number of points

drawOval

void drawOval(int x,
              int y,
              int width,
              int height)

Draws an ellipse.

Parameters:

x - x-location

y - y-location

width - width

height - height

fillOval

void fillOval(int x,
              int y,
              int width,
              int height)

Draws a filled ellipse.

Parameters:

x - x-location

y - y-location

width - width

height - height

setColor

void setColor(int c)

Sets the drawing color. The value is an ARGB value. This means that an opaque color has the format 0xFFrrggbb.

Specified by:

setColor in interface Graphics

Parameters:

c - new drawing color (ARGB value)

setColor

void setColor(Color c)

Sets the drawing color.

Parameters:

c - new drawing color

getColor

int getColor()

Returns the ARGB value of the current drawing color.

Returns:

drawing color (ARGB value)

setBackground

void setBackground(int c)

Sets the background color. The value is an ARGB value. This means that an opaque color has the format 0xFFrrggbb.

Specified by:

setBackground in interface Graphics

Parameters:

c - new background color (ARGB value)

setBackground

void setBackground(Color c)

Sets the background color.

Parameters:

c - new background color

getBackground

int getBackground()

Returns the ARGB value of the current background color.

Returns:

background color (ARGB value)

swapColors

void swapColors()

Swaps drawing and background color.

drawChar

int drawChar(char c,
             int x,
             int y)

Draws a single character with the currently set font.

Specified by:

drawChar in interface Graphics

Parameters:

c - character to draw

x - x-location

y - y-location

Returns:

width of the visible part(!) of the drawn character

See Also:

Graphics.setFont(Object), Graphics.drawString(String, int, int)

drawChar

int drawChar(char c,
             int x,
             int y,
             int anchor)

Draws a single character with the currently set font. An anchor can be used to specify the alignment of the character to the defined location.

Parameters:

c - character to draw

x - x-location

y - y-location

anchor - character alignment (e.g. ANCHOR_HCENTER or ANCHOR_BASELINE, ...)

Returns:

width of the visible part(!) of the drawn character

drawString

void drawString(String s,
                int x,
                int y,
                int anchor)

Draws a text string with the currently set font. An anchor can be used to specify the alignment of the text to the defined location.

Parameters:

s - text to draw

x - x-location

y - y-location

anchor - text alignment (e.g. ANCHOR_HCENTER or ANCHOR_BASELINE, ...)

getFont

Object getFont()

Returns the currently set font.

Returns:

font

drawImage

void drawImage(Object drawable,
               int x,
               int y,
               int anchor)

Draws an image. An anchor can be used to specify the alignment of the image to the defined location.

Parameters:

drawable - drawable object (e.g. Image or a Resource containing a bitmap image)

x - x-location

y - y-location

anchor - image alignment (e.g. ANCHOR_HCENTER or ANCHOR_TOP, ...)

setClip

void setClip(int x,
             int y,
             int width,
             int height)

Sets the clipping rectangle. The only limit is the size of the underlying framebuffer. This method should be handled with care from within graphical frameworks like Xui, because it can enable access to the whole screen at any time, opening the door for graphical errors.

The coordinates are treated as relative to the current translation point.

Parameters:

x - new x-location of the clipping rectangle

y - new x-location of the clipping rectangle

width - new width of the clipping rectangle

height - new height of the clipping rectangle

clipRect

boolean clipRect(int x,
                 int y,
                 int width,
                 int height)

Downsizes the current clipping rectangle by intersection with the given rectangle. That means that the new clipping rectangle covers the area the was lying in both, the old clipping rectangle and the intersection rectangle.

The coordinates are treated as relative to the current translation point.

Parameters:

x - x-location of intersection rectangle

y - y-location of intersection rectangle

width - width of intersection rectangle

height - height of intersection rectangle

Returns:

true, if resulting clipping rectangle is not empty

getClipX

int getClipX()

Returns the current clipping rectangle's x-location relatively to the translation point.

Returns:

x-location

getClipY

int getClipY()

Returns the current clipping rectangle's y-location relatively to the translation point.

Returns:

y-location

getClipWidth

int getClipWidth()

Returns the current clipping rectangle's width.

Returns:

width

getClipHeight

int getClipHeight()

Returns the current clipping rectangle's height.

Returns:

height

isOverlapping

boolean isOverlapping(int x,
                      int y,
                      int width,
                      int height)

Checks, if the given rectangle overlaps (or - mathematically spoken - intersects) with the current clipping rectangle.

The coordinates are treated as relative to the current translation point.

Parameters:

x - x-location of rectangle to test

y - y-location of rectangle to test

width - width of rectangle to test

height - height of rectangle to test

Returns:

true, if the two rectangles are overlapping each other, otherwise false

isClipRectEmpty

boolean isClipRectEmpty()

Checks, if the current clipping rectangle is empty (i.e. doesn't cover any pixel).

Returns:

true, if clipping rectangle is empty

copyArea

void copyArea(int x,
              int y,
              int width,
              int height,
              int dx,
              int dy)

Copies an area within the framebuffer. The draw mode gets ignored here.

Parameters:

x - x-location of area to copy

y - y-location of area to copy

width - width of area to copy

height - height of area to copy

dx - destination x-location

dy - destination y-location

translate

void translate(int dx,
               int dy)

Moves the translation (origin) point.

Parameters:

dx - horizontal translation

dy - vertical translation

getTranslateX

int getTranslateX()

Get's the translation point's x-location.

Returns:

x-location

getTranslateY

int getTranslateY()

Get's the translation point's y-location.

Returns:

y-location

cloneXGraphics

XGraphics cloneXGraphics()

Creates a clone of this XGraphics object that has the same settings as this one, but acts independently.

Returns:

clone