An
Image
represents a displayable image, which can be read from a file or URL,
or constructed as a memory resident image using the built-ins defined in the
Graphics
object that is associated with the image.
Images can be used for a variety of purposes, including custom cursors that
can be assigned to any AWT or Swing component.
The fields in an
Image
are:
| background |
The
Color
that is used to paint the background of the image.
A
NULL
value means paint with a default color, which is usually
VM.screen.background.
The background color is normally only noticed when an image is constructed
in memory.
Reading returns a snapshot of the current color.
Writing immediately reconstructs the image using the new background color.
| | columns |
A read-only
int
that specifies the number of pixels that span the image horizontally.
| | convert |
A
Builtin
that changes a selected group of pixels in this image.
| | convolve |
A
Builtin
that assigns values to the pixels in this image that are based on the
values stored in neighboring pixels.
| | flags |
A read-only
int
that is a bitmask that represents the current state of the image.
The value will be a bitwise-ORing of the constants
IMAGE_ABORT,
IMAGE_ALLBITS,
IMAGE_ERROR,
IMAGE_FRAMEBITS,
IMAGE_HEIGHT,
IMAGE_PROPERTIES,
IMAGE_SOMEBITS,
and
IMAGE_WIDTH,
which are all defined in
yoix.image.
| | getpixel |
A
Builtin
that returns the
Color
of a pixel in this image.
| | graphics |
A
Graphics
object that defines properties and built-ins that are used to apply
graphics operations to this image.
Writing after an image has been created is not allowed and will result in an
invalidaccess
error.
invalidaccess
error.
| | hotspot |
A
Point
that defines the location of the hotspot when this image is used to create
a custom cursor.
A
hotspot
that lies outside the image is quietly repositioned when a cursor is created.
Setting
hotspot
in the image's
paint
function is convenient because
paint
will be called if the image's size is changed, which can happen when
a cursor is created.
The default
hotspot,
if you do not specify one, is the image's upper left corner.
| | metrics |
A
Number
or an
Array
of two or four numbers that control how
showimage
places the image and adjusts the current point after the image is drawn;
the numbers are always multiplied by the image's width or height to get
actual distances.
When
metrics
is an array of four numbers,
the first two are x and y side bearings that control where the image's
upper left corner goes relative to the current point,
while the last two numbers are x and y widths that are added to the
current point after the image is drawn.
An array of two numbers sets the horizontal side bearing and width,
while a single number only sets the horizontal width.
| | model |
An
int
that controls some of the low level image support code.
A value of
-1,
which is currently the default, tries to provide some backward compatibility,
primarily in the way the
source
field is handled.
The default value may be changed in a future release.
| | opaque |
A read-only
int
that is zero when the image supports an alpha channel and non-zero otherwise.
| | paint([Rectangle rect]) |
A
Function
that is called, if it is not
NULL,
whenever the image is reconstructed.
The optional
rect
argument describes the rectangle that needs repainting in the
coordinate system specified by
graphics.CTM,
which by default has its origin at the image's upper left corner,
positive x to the right, positive y down, and a resolution of 72 dots per inch.
| | preferredsize |
A
Dimension
that represents the image's natural size in units of 72 dots per inch.
The fields in
preferredsize
and
size
match when a memory resident image is created (i.e.,
source
is
NULL)
or when an image is read from a file or URL and no
size
is set.
Reading returns a snapshot of the image's preferred size.
Writing is not allowed and will result in an
invalidaccess
error.
| | repaint |
A
Builtin
that tells the image to completely repaint itself.
| | replace |
A
Builtin
that uses lookup tables to change the color components of each pixel
in this image.
| | rescale |
A
Builtin
that applies linear transformations to the color components of each pixel
in this image.
| | rows |
A read-only
int
that specifies the number of pixels that span the image vertically.
| | setpixel |
A
Builtin
that sets the
Color
of a pixel in this image.
| | size |
A
Dimension
that determines the actual size of the image in units of 72 dots per inch.
size
must be set when a memory resident image (i.e.,
source
is
NULL)
is created.
Reading returns a snapshot of the current size.
Writing immediately reconstructs the image and scales it to the new size.
| | source |
A
String
or
Image
that determines where the pixels stored in this image came from.
If
source
is a
String
then it should name a local a file or URL that contains a GIF or JPEG image.
If
source
is an
Image
then the pixels stored in
source
are copied into this image, which means both images will be completely
independent.
Setting
source
to
NULL
means create a memory resident image that is exactly as big as the
size
field specifies.
The empty string (i.e.,
"")
is treated just like
NULL
when
model
is
-1,
which is currently the default, but is subject to change in future releases.
Writing disposes this image and reconstructs a new one.
| | transform |
A
Builtin
that applies an affine transformation to this image.
| | type |
An
int
that identifies the
type
of this image.
The value should usually be one of
TYPE_RGB,
TYPE_RGBA,
TYPE_RGB_COMPACT,
TYPE_GRAY,
TYPE_GRAY_COMPACT,
TYPE_BINARY,
or
TYPE_INDEXED,
which are self-explanatory constants defined in
yoix.image.
The full set of constants that identify the image types supported by Java
are also defined in
yoix.image,
but the list is long and will not be reproduced here.
Unrecognized values are automatically mapped to
TYPE_RGB,
while several types based on shorts that caused problems on some of our
test platforms may be mapped to other values.
Writing a new value immediately changes the image to that
type.
|
Several permanent fields have not been documented and should not be
used in Yoix applications.
Yoix images, unlike their Java counterparts, are always loaded and completely
constructed by the current thread.
Point an image's
source
field at a URL and the current thread will wait until there is an error or
the image is completely constructed.
Loading images in separate threads is not difficult:
one approach is outlined in the examples below.
We have also included a simple example that shows how an image can be used
to create a custom cursor.
| |
| Example: |
The first program,
import yoix.*.*;
Image img = {
String source = "http://www.yoix.org/imgs/ATTlogo.gif";
Dimension size = {
double height = 72;
double width = 72*2;
};
Graphics graphics = {
Color foreground = Color.red;
};
paint() {
String label = "Image Test";
double dx;
double dy;
graphics {
dx = stringwidth(label);
dy = font.descent;
moveto(size.width - dx, size.height - dy);
show(label);
}
}
};
JFrame f = {
Image backgroundimage = img;
int backgroundhints = SCALE_TILE;
};
f.visible = TRUE;
sleep(5);
exit(0);
reads an image from a URL, scales it so it is 1 inch high and 2 inches wide,
adds a red text label to the lower right corner of the image,
tiles a frame with the image, and shows that frame for 5 seconds.
Change source to
NULL
and the program uses a blank memory resident image.
Custom cursors are built using images.
They can be assigned directly to the
cursor
or officially managed using the
addCursor
builtin, which makes an entry in
yoix.swing.Cursor
that gives other components efficient access to the new cursor
(i.e., Java's low level cursor building only happens once).
The following program,
import yoix.*.*;
JFrame frame = {
Image cursor = {
int type = TYPE_RGBA;
Dimension size = {
double width = 72/3;
double height = 72/3;
};
Graphics graphics = {
int rendering = 1; // probably no help
int antialiasing = 1;
};
paint(Rectangle r) {
Rectangle bbox;
double thickness;
double radius;
double alpha;
double cx;
double cy;
graphics {
gsave();
initgraphics();
clippath();
bbox = pathbbox();
newpath();
cx = bbox.width/2;
cy = bbox.height/2;
thickness = cx/4.0;
radius = cx - thickness - 1;
alpha = 180*atan2(thickness/2, radius)/PI;
translate(cx, cy);
rotate(45);
moveto(0, thickness/2);
arc(0, 0, radius, alpha, 180 - alpha);
closepath();
moveto(0, -thickness/2);
arc(0, 0, radius, 180 + alpha, 360 - alpha);
closepath();
moveto(radius + thickness, 0);
arc(0, 0, radius + thickness, 0, 360);
closepath();
gsave();
setrgbcolor(1, 0, 0);
eofill();
grestore();
setlinewidth(1);
setrgbcolor(1, 1, 1);
stroke();
grestore();
hotspot = new Point {
double x = cx;
double y = cy;
};
}
}
};
};
frame.visible = TRUE;
shows how you use an image's
paint,
hotspot,
size,
and
type
fields to paint a picture in a image that can then be used as a
JFrame's
cursor.
The next program,
import yoix.*.*;
final double SHADOW = 72.0/36;
Image att = {
String source = "http://www.yoix.org/imgs/ATTlogo.gif";
};
Frame f = {
FlowLayout layoutmanager = {
int vgap = 72;
};
Array layout = {
new Canvas {
double border = SHADOW;
Color background = Color.gray;
Image backgroundimage = att;
int backgroundhints = SCALE_DEFAULT;
int state = FALSE;
Dimension size = {
double width = att.size.width + 2*SHADOW;
double height = att.size.height + 2*SHADOW;
};
actionPerformed(ActionEvent e) {
printf("URL=%s\n", att.source);
}
}
};
};
f.visible = TRUE;
sleep(5);
exit(0);
shows how to build a custom button out of a AWT canvas that displays
an image rather than a text string.
Swing makes the job a little easier, because a
JButton
has a field named
icon
that you can use when you want to display an image in a button.
The last program,
import yoix.stdio.*;
ImageLoader(String path, Function function) {
Thread thread;
loader(String path, Function function) {
Image image;
image.source = path; // load the image
if (function != NULL)
function(image);
}
thread.queue(loader, path, function);
}
Observer(arg, ...) {
printf("loaded %O\n", arg);
}
ImageLoader("http://www.yoix.org/imgs/ATTlogo.gif", Observer);
shows how you can easily load images in separate threads and
call a function that we named
Observer
when the image construction stops.
In a real application
Observer
would be more complicated and would almost certainly always check the
flags
field to make sure the image loaded properly.
| | |
| See Also: |
addCursor,
Border,
Canvas,
decodeJPEG,
Dialog,
encodeJPEG,
Frame,
getBestCursorSize,
Graphics,
JButton,
JCanvas,
JDesktopPane,
JDialog,
JFileDialog,
JFrame,
JInternalFrame,
JLabel,
JLayeredPane,
JMenuItem,
JMenu,
JPanel,
JScrollPane,
JSplitPane,
JTabbedPane,
JWindow,
Panel,
Window
|
|
