| package org.eclipse.swt.graphics; |
| |
| /* |
| * (c) Copyright IBM Corp. 2000, 2001. |
| * All Rights Reserved |
| */ |
| |
| import org.eclipse.swt.internal.gtk.*; |
| import org.eclipse.swt.widgets.*; |
| import org.eclipse.swt.*; |
| import java.io.*; |
| |
| /** |
| * Instances of this class are graphics which have been prepared |
| * for display on a specific device. That is, they are ready |
| * to paint using methods such as <code>GC.drawImage()</code> |
| * and display on widgets with, for example, <code>Button.setImage()</code>. |
| * <p> |
| * If loaded from a file format that supports it, an |
| * <code>Image</code> may have transparency, meaning that certain |
| * pixels are specified as being transparent when drawn. Examples |
| * of file formats that support transparency are GIF and PNG. |
| * </p><p> |
| * There are two primary ways to use <code>Images</code>. |
| * The first is to load a graphic file from disk and create an |
| * <code>Image</code> from it. This is done using an <code>Image</code> |
| * constructor, for example: |
| * <pre> |
| * Image i = new Image(device, "C:\\graphic.bmp"); |
| * </pre> |
| * A graphic file may contain a color table specifying which |
| * colors the image was intended to possess. In the above example, |
| * these colors will be mapped to the closest available color in |
| * SWT. It is possible to get more control over the mapping of |
| * colors as the image is being created, using code of the form: |
| * <pre> |
| * ImageData data = new ImageData("C:\\graphic.bmp"); |
| * RGB[] rgbs = data.getRGBs(); |
| * // At this point, rgbs contains specifications of all |
| * // the colors contained within this image. You may |
| * // allocate as many of these colors as you wish by |
| * // using the Color constructor Color(RGB), then |
| * // create the image: |
| * Image i = new Image(device, data); |
| * </pre> |
| * <p> |
| * Applications which require even greater control over the image |
| * loading process should use the support provided in class |
| * <code>ImageLoader</code>. |
| * </p><p> |
| * Application code must explicitely invoke the <code>Image.dispose()</code> |
| * method to release the operating system resources managed by each instance |
| * when those instances are no longer required. |
| * </p> |
| * |
| * @see Color |
| * @see ImageData |
| * @see ImageLoader |
| */ |
| public final class Image implements Drawable{ |
| |
| /** |
| * specifies whether the receiver is a bitmap or an icon |
| * (one of <code>SWT.BITMAP</code>, <code>SWT.ICON</code>) |
| */ |
| public int type; |
| |
| /** |
| * The handle to the OS pixmap resource. |
| * Warning: This field is platform dependent. |
| */ |
| public int pixmap; |
| |
| /** |
| * The handle to the OS mask resource. |
| * Warning: This field is platform dependent. |
| */ |
| public int mask; |
| |
| /** |
| * The device where this image was created. |
| */ |
| Device device; |
| |
| /** |
| * specifies the transparent pixel |
| * (Warning: This field is platform dependent) |
| */ |
| int transparentPixel = -1; |
| |
| /** |
| * The GC the image is currently selected in. |
| * Warning: This field is platform dependent. |
| */ |
| GC memGC; |
| |
| /** |
| * The alpha data of the image. |
| * Warning: This field is platform dependent. |
| */ |
| byte[] alphaData; |
| |
| /** |
| * The global alpha value to be used for every pixel. |
| * Warning: This field is platform dependent. |
| */ |
| int alpha = -1; |
| |
| /** |
| * Specifies the default scanline padding. |
| * Warning: This field is platform dependent. |
| */ |
| static final int DEFAULT_SCANLINE_PAD = 4; |
| |
| |
| |
| /* |
| * CONSTRUCTORS |
| */ |
| |
| Image() { |
| } |
| |
| /** |
| * Constructs an empty instance of this class with the |
| * specified width and height. The result may be drawn upon |
| * by creating a GC and using any of its drawing operations, |
| * as shown in the following example: |
| * <pre> |
| * Image i = new Image(device, width, height); |
| * GC gc = new GC(i); |
| * gc.drawRectangle(0, 0, 50, 50); |
| * gc.dispose(); |
| * </pre> |
| * |
| * @param device the device on which to create the image |
| * @param width the width of the new image |
| * @param height the height of the new image |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_INVALID_ARGUMENT - if either the width or height is negative</li> |
| * </ul> |
| */ |
| public Image(Device display, int width, int height) { |
| init(display, width, height); |
| } |
| |
| /** |
| * Constructs a new instance of this class based on the |
| * provided image, with an appearance that varies depending |
| * on the value of the flag. The possible flag values are: |
| * <dl> |
| * <dt><b>IMAGE_COPY</b></dt> |
| * <dd>the result is an identical copy of srcImage</dd> |
| * <dt><b>IMAGE_DISABLE</b></dt> |
| * <dd>the result is a copy of srcImage which has a <em>disabled</em> look</dd> |
| * <dt><b>IMAGE_GRAY</b></dt> |
| * <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd> |
| * </dl> |
| * |
| * @param device the device on which to create the image |
| * @param srcImage the image to use as the source |
| * @param flag the style, either <code>IMAGE_COPY</code>, <code>IMAGE_DISABLE</code> or <code>IMAGE_GRAY</code> |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_NULL_ARGUMENT - if srcImage is null</li> |
| * <li>ERROR_INVALID_ARGUMENT - if the flag is not one of <code>IMAGE_COPY</code>, <code>IMAGE_DISABLE</code> or <code>IMAGE_GRAY</code></li> |
| * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> |
| * </ul> |
| * @exception SWTException <ul> |
| * <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon, or |
| * is otherwise in an invalid state</li> |
| * </ul> |
| * @exception SWTError <ul> |
| * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> |
| * </ul> |
| */ |
| public Image(Device device, Image srcImage, int flag) { |
| /* basic sanity */ |
| if (device == null) device = Device.getDevice(); |
| if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| this.device = device; |
| if (srcImage == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (srcImage.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT); |
| this.type = srcImage.type; |
| this.mask = 0; |
| |
| /* this is somewhat ugly, because this dilutes the encapsulation |
| * of knowledge about what the cloning operations do (e.g., the |
| * following lines assume graying and disabling don't change alpha) |
| */ |
| this.alphaData = srcImage.alphaData; |
| this.alpha = srcImage.alpha; |
| this.transparentPixel = srcImage.transparentPixel; |
| // bogus - are we sure about memGC? |
| |
| /* Special case: |
| * If all we want is just a clone of the existing pixmap, it can |
| * be done entirely in the X server, without copying across the net. |
| */ |
| if (flag == SWT.IMAGE_COPY) { |
| int[] unused = new int[1]; |
| int[] width = new int[1]; int[] height = new int[1]; |
| int[] depth = new int[1]; |
| OS.gdk_window_get_geometry(pixmap, unused, unused, width, height, depth); |
| pixmap = OS.gdk_pixmap_new (0, width[0], height[0], depth[0]); |
| int gc = OS.gdk_gc_new (pixmap); |
| OS.gdk_draw_pixmap(pixmap, gc, srcImage.pixmap, |
| 0,0,0,0, width[0], height[0]); |
| OS.gdk_gc_destroy(gc); |
| transparentPixel = srcImage.transparentPixel; |
| alpha = srcImage.alpha; |
| if (srcImage.alphaData != null) { |
| alphaData = new byte[srcImage.alphaData.length]; |
| System.arraycopy(srcImage.alphaData, 0, alphaData, 0, alphaData.length); |
| } |
| |
| /* we are not quite done yet. Need to copy the maskData */ |
| if (srcImage.mask != 0) { |
| /* Generate the mask if necessary. */ |
| // if (srcImage.transparentPixel != -1) srcImage.createMask(); |
| mask = OS.gdk_pixmap_new(0, width[0], height[0], 1); |
| gc = OS.gdk_gc_new(mask); |
| OS.gdk_draw_pixmap(mask, gc, srcImage.mask, |
| 0,0,0,0, width[0], height[0]); |
| OS.gdk_gc_destroy(gc); |
| /* Destroy the image mask if the there is a GC created on the image */ |
| if (srcImage.transparentPixel != -1 && srcImage.memGC != null) srcImage.destroyMask(); |
| } |
| |
| |
| return; |
| } |
| |
| |
| |
| |
| Pixbuffer pb = new Pixbuffer(srcImage); |
| Pixbuffer pb2 = new Pixbuffer(pb, flag); |
| pb2.toImage(this); |
| |
| |
| } |
| |
| /** |
| * Constructs an empty instance of this class with the |
| * width and height of the specified rectangle. The result |
| * may be drawn upon by creating a GC and using any of its |
| * drawing operations, as shown in the following example: |
| * <pre> |
| * Image i = new Image(device, boundsRectangle); |
| * GC gc = new GC(i); |
| * gc.drawRectangle(0, 0, 50, 50); |
| * gc.dispose(); |
| * </pre> |
| * |
| * @param device the device on which to create the image |
| * @param bounds a rectangle specifying the image's width and height (must not be null) |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_NULL_ARGUMENT - if the bounds rectangle is null</li> |
| * <li>ERROR_INVALID_ARGUMENT - if either the rectangle's width or height is negative</li> |
| * </ul> |
| */ |
| public Image(Device display, Rectangle bounds) { |
| if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| init(display, bounds.width, bounds.height); |
| } |
| |
| /** |
| * Constructs an instance of this class from the given |
| * <code>ImageData</code>. |
| * |
| * @param device the device on which to create the image |
| * @param data the image data to create the image from (must not be null) |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_NULL_ARGUMENT - if the image data is null</li> |
| * </ul> |
| */ |
| public Image(Device display, ImageData image) { |
| if (image == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (display == null) display = Display.getDefault(); |
| init(display, image); |
| } |
| |
| /** |
| * Constructs an instance of this class, whose type is |
| * <code>SWT.ICON</code>, from the two given <code>ImageData</code> |
| * objects. The two images must be the same size, and the mask image |
| * must have a color depth of 1. Pixel transparency in either image |
| * will be ignored. If either image is an icon to begin with, an |
| * exception is thrown. |
| * <p> |
| * The mask image should contain white wherever the icon is to be visible, |
| * and black wherever the icon is to be transparent. In addition, |
| * the source image should contain black wherever the icon is to be |
| * transparent. |
| * </p> |
| * |
| * @param device the device on which to create the icon |
| * @param source the color data for the icon |
| * @param mask the mask data for the icon |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_NULL_ARGUMENT - if either the source or mask is null </li> |
| * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes or |
| * if the mask is not monochrome, or if either the source or mask |
| * is already an icon</li> |
| * </ul> |
| */ |
| public Image(Device display, ImageData source, ImageData mask) { |
| if (source == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (mask == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (display == null) display = Display.getDefault(); |
| if (source.width != mask.width || source.height != mask.height) SWT.error(SWT.ERROR_INVALID_ARGUMENT); |
| if (mask.depth != 1) SWT.error(SWT.ERROR_INVALID_ARGUMENT); |
| ImageData image; |
| if (source.depth != 1) |
| image = new ImageData(source.width, source.height, source.depth, source.palette, source.scanlinePad, source.data); |
| else { |
| image = source.getTransparencyMask(); //create an imagedata with scanlinepad == 1 and invalid data |
| int[] row = new int[source.width]; |
| for (int y = 0; y < source.height; y++) { |
| source.getPixels(0, y, source.width, row, 0); |
| image.setPixels(0, y, source.width, row, 0); |
| }//change source data format from scanlinePad == 4 to scanlinePad == 1; |
| |
| } |
| image.type = SWT.ICON; |
| image.maskPad = mask.scanlinePad; |
| image.maskData = mask.data; |
| init(display, image); |
| } |
| |
| /** |
| * Constructs an instance of this class by loading its representation |
| * from the specified input stream. Throws an error if an error |
| * occurs while loading the image, or if the result is an image |
| * of an unsupported type. |
| * <p> |
| * This constructor is provided for convenience when loading a single |
| * image only. If the stream contains multiple images, only the first |
| * one will be loaded. To load multiple images, use |
| * <code>ImageLoader.load()</code>. |
| * </p><p> |
| * This constructor may be used to load a resource as follows: |
| * </p> |
| * <pre> |
| * new Image(device, clazz.getResourceAsStream("file.gif")); |
| * </pre> |
| * |
| * @param device the device on which to create the image |
| * @param stream the input stream to load the image from |
| * |
| * @exception SWTException <ul> |
| * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> |
| * <li>ERROR_IO - if an IO error occurs while reading data</li> |
| * </ul> |
| */ |
| public Image(Device display, InputStream stream) { |
| if (stream == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (display == null) display = Display.getDefault(); |
| init(display, new ImageData(stream)); |
| } |
| |
| /** |
| * Constructs an instance of this class by loading its representation |
| * from the file with the specified name. Throws an error if an error |
| * occurs while loading the image, or if the result is an image |
| * of an unsupported type. |
| * <p> |
| * This constructor is provided for convenience when loading |
| * a single image only. If the specified file contains |
| * multiple images, only the first one will be used. |
| * |
| * @param device the device on which to create the image |
| * @param filename the name of the file to load the image from |
| * |
| * @exception SWTException <ul> |
| * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> |
| * <li>ERROR_IO - if an IO error occurs while reading data</li> |
| * </ul> |
| */ |
| public Image(Device display, String filename) { |
| if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (display == null) display = Display.getDefault(); |
| init(display, new ImageData(filename)); |
| } |
| |
| /** |
| * Destroy the receiver's mask if it exists. |
| */ |
| void destroyMask() { |
| if (mask == 0) return; |
| OS.gdk_bitmap_unref(mask); |
| mask = 0; |
| } |
| |
| /** |
| * Disposes of the operating system resources associated with |
| * the image. Applications must dispose of all images which |
| * they allocate. |
| */ |
| public void dispose () { |
| if (pixmap != 0) OS.gdk_pixmap_unref(pixmap); |
| if (mask != 0) OS.gdk_pixmap_unref(mask); |
| pixmap = mask = 0; |
| memGC = null; |
| } |
| /** |
| * Compares the argument to the receiver, and returns true |
| * if they represent the <em>same</em> object using a class |
| * specific comparison. |
| * |
| * @param object the object to compare with this object |
| * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise |
| * |
| * @see #hashCode |
| */ |
| public boolean equals (Object object) { |
| return (object == this) || ((object instanceof Image) && |
| (pixmap == ((Image)object).pixmap) && |
| (mask == ((Image)object).mask)); |
| } |
| |
| /** |
| * Returns the color to which to map the transparent pixel, or null if |
| * the receiver has no transparent pixel. |
| * <p> |
| * There are certain uses of Images that do not support transparency |
| * (for example, setting an image into a button or label). In these cases, |
| * it may be desired to simulate transparency by using the background |
| * color of the widget to paint the transparent pixels of the image. |
| * Use this method to check which color will be used in these cases |
| * in place of transparency. This value may be set with setBackground(). |
| * <p> |
| * |
| * @return the background color of the image, or null if there is no transparency in the image |
| * |
| * @exception SWTException <ul> |
| * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> |
| * </ul> |
| */ |
| public Color getBackground() { |
| return null; |
| } |
| |
| /** |
| * Sets the color to which to map the transparent pixel. |
| * <p> |
| * There are certain uses of <code>Images</code> that do not support |
| * transparency (for example, setting an image into a button or label). |
| * In these cases, it may be desired to simulate transparency by using |
| * the background color of the widget to paint the transparent pixels |
| * of the image. This method specifies the color that will be used in |
| * these cases. For example: |
| * <pre> |
| * Button b = new Button(); |
| * image.setBackground(b.getBackground());> |
| * b.setImage(image); |
| * </pre> |
| * </p><p> |
| * The image may be modified by this operation (in effect, the |
| * transparent regions may be filled with the supplied color). Hence |
| * this operation is not reversible and it is not legal to call |
| * this function twice or with a null argument. |
| * </p><p> |
| * This method has no effect if the receiver does not have a transparent |
| * pixel value. |
| * </p> |
| * |
| * @param color the color to use when a transparent pixel is specified |
| * |
| * @exception IllegalArgumentException <ul> |
| * <li>ERROR_NULL_ARGUMENT - if the color is null</li> |
| * <li>ERROR_INVALID_ARGUMENT - if the color has been disposed</li> |
| * </ul> |
| * @exception SWTException <ul> |
| * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> |
| * </ul> |
| */ |
| public void setBackground(Color color) { |
| if (color == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (color.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT); |
| } |
| |
| /** |
| * Returns the bounds of the receiver. The rectangle will always |
| * have x and y values of 0, and the width and height of the |
| * image. |
| * |
| * @return a rectangle specifying the image's bounds |
| * |
| * @exception SWTException <ul> |
| * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> |
| * <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon</li> |
| * </ul> |
| */ |
| public Rectangle getBounds() { |
| int[] unused = new int[1]; int[] width = new int[1]; int[] height = new int[1]; |
| OS.gdk_window_get_geometry(pixmap, unused, unused, width, height, unused); |
| return new Rectangle(0, 0, width[0], height[0]); |
| |
| } |
| /** |
| * Returns an <code>ImageData</code> based on the receiver |
| * Modifications made to this <code>ImageData</code> will not |
| * affect the Image. |
| * |
| * @return an <code>ImageData</code> containing the image's data and attributes |
| * |
| * @exception SWTException <ul> |
| * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> |
| * <li>ERROR_INVALID_IMAGE - if the image is not a bitmap or an icon</li> |
| * </ul> |
| * |
| * @see ImageData |
| */ |
| public ImageData getImageData() { |
| return new Pixbuffer(this).getImageData(); |
| } |
| |
| public static Image gtk_new(int type, int pixmap, int mask) { |
| Image image = new Image(); |
| image.type = type; |
| image.pixmap = pixmap; |
| image.mask = mask; |
| return image; |
| } |
| /** |
| * Returns an integer hash code for the receiver. Any two |
| * objects which return <code>true</code> when passed to |
| * <code>equals</code> must return the same value for this |
| * method. |
| * |
| * @return the receiver's hash |
| * |
| * @see #equals |
| */ |
| public int hashCode () { |
| return pixmap; |
| } |
| /** |
| * Invokes platform specific functionality to allocate a new GC handle. |
| * <p> |
| * <b>IMPORTANT:</b> This method is <em>not</em> part of the public |
| * API for <code>Image</code>. It is marked public only so that it |
| * can be shared within the packages provided by SWT. It is not |
| * available on all platforms, and should never be called from |
| * application code. |
| * </p> |
| * |
| * @param data the platform specific GC data |
| * @return the platform specific GC handle |
| * |
| * @private |
| */ |
| public int internal_new_GC (GCData data) { |
| if (pixmap == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); |
| if (data == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); |
| if (type != SWT.BITMAP || memGC != null) { |
| SWT.error(SWT.ERROR_INVALID_ARGUMENT); |
| } |
| |
| data.image = this; |
| int gc = OS.gdk_gc_new(pixmap); |
| data.drawable = pixmap; |
| return gc; |
| } |
| /** |
| * Invokes platform specific functionality to dispose a GC handle. |
| * <p> |
| * <b>IMPORTANT:</b> This method is <em>not</em> part of the public |
| * API for <code>Image</code>. It is marked public only so that it |
| * can be shared within the packages provided by SWT. It is not |
| * available on all platforms, and should never be called from |
| * application code. |
| * </p> |
| * |
| * @param handle the platform specific GC handle |
| * @param data the platform specific GC data |
| * |
| * @private |
| */ |
| public void internal_dispose_GC (int gc, GCData data) { |
| OS.gdk_gc_unref(gc); |
| } |
| |
| void init(Device display, int width, int height) { |
| device = display; |
| GdkVisual visual = new GdkVisual (); |
| OS.memmove(visual, OS.gdk_visual_get_system(), GdkVisual.sizeof); |
| this.pixmap = OS.gdk_pixmap_new(0, width, height, visual.depth); |
| if (pixmap == 0) SWT.error(SWT.ERROR_NO_HANDLES); |
| /* Fill the bitmap with white */ |
| GdkColor white = new GdkColor(); |
| int colormap = OS.gdk_colormap_get_system(); |
| OS.gdk_color_white(colormap, white); |
| int gc = OS.gdk_gc_new(pixmap); |
| OS.gdk_gc_set_foreground(gc, white); |
| OS.gdk_draw_rectangle(pixmap, gc, 1, 0, 0, width, height); |
| OS.gdk_gc_destroy(gc); |
| OS.gdk_colors_free(colormap, new int[] { white.pixel }, 1, 0); |
| this.type = SWT.BITMAP; |
| } |
| |
| void init(Device display, ImageData image) { |
| if (image == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); |
| if (display == null) display = Display.getCurrent(); |
| device = display; |
| |
| /* |
| * We don't really care about the real depth of the ImageData we are |
| * given. We stretch everything to 24bpp which is the native GdkPixbuffer |
| * depth. HOWEVER, there is one situation where this is not acceptable, |
| * namely bitmaps (1bpp), because they may be used in contexts that are |
| * sensitive to pixmap depth. |
| */ |
| Pixbuffer buff = new Pixbuffer(image); |
| buff.toImage(this); |
| return; |
| } |
| |
| /** |
| * Returns <code>true</code> if the image has been disposed, |
| * and <code>false</code> otherwise. |
| * <p> |
| * This method gets the dispose state for the image. |
| * When an image has been disposed, it is an error to |
| * invoke any other method using the image. |
| * |
| * @return <code>true</code> when the image is disposed and <code>false</code> otherwise |
| */ |
| public boolean isDisposed() { |
| return pixmap == 0; |
| } |
| |
| /** |
| * Returns a string containing a concise, human-readable |
| * description of the receiver. |
| * |
| * @return a string representation of the receiver |
| */ |
| public String toString () { |
| if (isDisposed()) return "Image {*DISPOSED*}"; |
| return "Image {" + pixmap + "}"; |
| } |
| |
| } |