public class GraphicsContext extends Object
GraphicsContext provides access to a modifiable pixel buffer.
For example, a graphics context can be used to read or write the pixels of the Display or of a
BufferedImage.
Painting classes such as Painter provide utility methods to draw specific shapes and objects using a graphics
context.
Colors are interpreted as 24-bit RGB colors. If the display or image associated with the graphics context does not support such color depth, its implementation is in charge of mapping the desired colors to the most appropriate supported colors.
A graphics context defines a translation vector in order to change the position of subsequent drawings.
It also defines a clipping rectangle which restricts the pixels that will be modified by subsequent drawings. Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed. The position of this clipping area is relative to the origin of this graphics context, regardless of the value of the translation vector.
A graphics context uses the following coordinate system:
| Modifier and Type | Field and Description |
|---|---|
static int |
OPAQUE
Maximum opacity.
|
static int |
TRANSPARENT
Minimum opacity.
|
| Modifier and Type | Method and Description |
|---|---|
void |
disableEllipsis()
Disables ellipsis.
|
void |
enableEllipsis(int width)
Enables ellipsis when drawing characters.
|
static int |
getAlpha(int opacityPercent)
Returns the alpha level for the given opacity percentage.
|
int |
getBackgroundColor()
Returns the background color of this graphics context.
|
int |
getClipHeight()
Returns the height of the clipping area of this graphics context.
|
int |
getClipWidth()
Returns the width of the clipping area of this graphics context.
|
int |
getClipX()
Returns the x coordinate of the clipping area of this graphics context.
|
int |
getClipY()
Returns the y coordinate of the clipping area of this graphics context.
|
int |
getColor()
Returns the color of this graphics context.
|
int |
getEllipsisWidth()
Returns the width limit before applying the ellipsis.
|
int |
getHeight()
Returns the height of this graphics context.
|
byte[] |
getSNIContext()
Returns the SNI context data of this graphics context.
|
int |
getTranslationX()
Returns the x coordinate of the translation vector of this graphics context.
|
int |
getTranslationY()
Returns the y coordinate of the translation vector of this graphics context.
|
int |
getWidth()
Returns the width of this graphics context.
|
boolean |
hasBackgroundColor()
Returns whether this graphics context has a background color.
|
void |
intersectClip(int x,
int y,
int width,
int height)
Combines the given clipping rectangle with the clipping area of this graphics context.
|
int |
readPixel(int x,
int y)
Returns the color of a pixel of this graphics context.
|
void |
readPixels(int[] buffer,
int offset,
int scanLength,
int x,
int y,
int width,
int height)
Retrieves the color of the pixels of a region of this graphics context.
|
void |
removeBackgroundColor()
Removes the background color of this graphics context.
|
void |
reset()
Resets this graphics context to its initial configuration.
|
void |
resetClip()
Resets the clipping area of this graphics context to its entire bounds.
|
void |
resetTranslation()
Resets the translation vector of this graphics context to the
(0,0) vector. |
void |
setBackgroundColor(int color)
Sets the background color of this graphics context.
|
void |
setClip(int x,
int y,
int width,
int height)
Sets the clipping area of this graphics context to the given rectangle.
|
void |
setColor(int color)
Sets the color of this graphics context.
|
void |
setTranslation(int x,
int y)
Sets the translation vector of this graphics context to the
(x,y) vector. |
void |
translate(int x,
int y)
Adds a given translation vector to the translation vector of this graphics context.
|
public static final int OPAQUE
The opacity level (called alpha) is used by some Painter drawing methods to specify the
drawing global opacity. When the opacity is maximal, the drawing is fully opaque. When opacity is a value between
TRANSPARENT and OPAQUE, the drawing is merging the foreground color with the destination pixel
color or with the global background color. When the opacity is TRANSPARENT, the drawing
is fully transparent (nothing is drawn).
The opacity is an unsigned byte value between 0 (fully transparent) and 255 (fully opaque). All other values are meaningless.
The method getAlpha(int) allows to convert an opacity expressed in percentage (0% means fully
transparent and 100% fully opaque) in an opacity understandable by the Painter drawing methods.
getAlpha(int),
Painter.drawImage(GraphicsContext, Image, int, int, int),
Constant Field Valuespublic static final int TRANSPARENT
See OPAQUE comment.
public void disableEllipsis()
public void enableEllipsis(int width)
When ellipsis is enabled, characters are truncated if their rendering width is higher than the specified width limit. In this case, the last visible character is replaced by the ellipsis character (three dots).
To configure ellipsis using the clipping area as text limit, the given width should be equal to
getClipX() + getClipWidth() - x, where x is the x coordinate of the drawing.
The ellipsis is only used by the methods drawing characters.
width - the width limit, in pixels.IllegalArgumentException - if width is negative or zero.public static int getAlpha(int opacityPercent)
The returned value may be used in some painting methods such as
Painter.drawImage(GraphicsContext, Image, int, int, int).
opacityPercent - the opacity, in percents.public int getBackgroundColor()
The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.
public int getClipHeight()
public int getClipWidth()
public int getClipX()
public int getClipY()
public int getColor()
The returned color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.
public int getEllipsisWidth()
If ellipsis is disabled, this method returns zero.
public int getHeight()
public byte[] getSNIContext()
The SNI context can be used to call a native method with SNI. This allows to identify and to use a graphics context in the native world in order to perform drawings on the graphics context or to use it as a source.
The data format is implementation specific.
MicroUIException - if this graphics context is associated with a resource which has been closed.public int getTranslationX()
public int getTranslationY()
public int getWidth()
public boolean hasBackgroundColor()
true if a background color has been set, false otherwise.public void intersectClip(int x,
int y,
int width,
int height)
This method sets the clipping area to be the intersection of the given rectangle with the current clipping area.
Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.
Given clip origin is translated according current graphics context translation.
x - the x coordinate of the rectangle, in pixels.y - the y coordinate of the rectangle, in pixels.width - the width of the rectangle, in pixels.height - the height of the rectangle, in pixels.public int readPixel(int x,
int y)
For more information on the format of the color value returned by this method, refer to the first paragraphs of
the centralized pixel reading documentation.
x - the x coordinate of the pixel.y - the y coordinate of the pixel.IllegalArgumentException - if the given pixel coordinates are out of the bounds of this graphics context.MicroUIException - if this graphics context is associated with a resource which has been closed.public void readPixels(int[] buffer,
int offset,
int scanLength,
int x,
int y,
int width,
int height)
Each pixel color is stored in 32-bit ARGB format, where the high-order byte contains the alpha channel and the
remaining bytes contain the red, green and blue channels, respectively. This is relevant regardless of the format
in which the pixels are stored internally. The alpha channel specifies the opacity of the pixel, ranging between
TRANSPARENT and OPAQUE.
The retrieved colors are not guaranteed to be identical to the colors from the original source. Indeed, color values may be resampled to reflect the display capabilities of the device. For example, red, green and blue pixels may all be represented by the same color value on a grayscale device.
On displays which do not support alpha blending, the alpha component will be equal to
OPAQUE for opaque pixels and TRANSPARENT for every other pixel.
On displays that support alpha blending, alpha channel values may be resampled to reflect the number of levels of
opacity supported by the display.
The data is stored in the given int array, which should be big enough to hold the color of all the
pixels of the region.
The scan length specifies the relative offset within the internal array between two pixels of consecutive rows. In order to prevent rows of stored pixels from overlapping, the absolute value of the scan length should be greater than or equal to the width of the region. Negative values of scan length are allowed if the order of rows is inverted in the internal array.
If an exception occurs during this method, the contents of the given array will remain unchanged.
buffer - the buffer in which the pixel data should be stored.offset - the index of the buffer at which the first pixel color should be stored.scanLength - the relative offset in the internal array between two corresponding pixels in consecutive rows.x - the x-coordinate of the top-left pixel of the region.y - the y-coordinate of the top-left pixel of the region.width - the width of the region.height - the height of the region.ArrayIndexOutOfBoundsException - if the buffer is not big enough to hold the color of all the pixels of the region.IllegalArgumentException - if a part of the region is out of the bounds of this graphics context.IllegalArgumentException - if the absolute value of scanLength is lower than width.MicroUIException - if this graphics context is associated with a resource which has been closed.public void removeBackgroundColor()
public void reset()
This methods
Colors.BLACK,public void resetClip()
The current graphics context translation is not taken into account.
public void resetTranslation()
(0,0) vector.public void setBackgroundColor(int color)
The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.
The background color is only used by some drawing methods. If the background color is not set, these algorithms have to read the destination pixel color and blend it with the desired color.
The background color is irrelevant for black and white displays.
color - the color to set.public void setClip(int x,
int y,
int width,
int height)
Empty clipping areas are supported, in which case no pixel will be modified when a drawing operation is performed.
Given clip origin is translated according current graphics context translation.
x - the x coordinate of the rectangle, in pixels.y - the y coordinate of the rectangle, in pixels.width - the width of the rectangle, in pixels.height - the height of the rectangle, in pixels.public void setColor(int color)
The given color value is interpreted as a 24-bit RGB color, where the high-order byte is ignored and the remaining bytes contain the red, green and blue channels, respectively.
color - the color to set.public void setTranslation(int x,
int y)
(x,y) vector.x - the x coordinate of the translation vector, in pixels.y - the y coordinate of the translation vector, in pixels.public void translate(int x,
int y)
The new translation vector is equal to the sum of the given translation vector and the current translation vector.
x - the x coordinate of the translation vector to add, in pixels.y - the y coordinate of the translation vector to add, in pixels.