home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1997 May / Pcwk0597.iso / sybase / starbuck / java.z / Graphics.java < prev    next >
Text File  |  1996-05-03  |  18KB  |  516 lines
  1. /*
  2.  * @(#)Graphics.java    1.30 96/03/19 Sami Shaio
  3.  *
  4.  * Copyright (c) 1995 Sun Microsystems, Inc. All Rights Reserved.
  5.  *
  6.  * Permission to use, copy, modify, and distribute this software
  7.  * and its documentation for NON-COMMERCIAL purposes and without
  8.  * fee is hereby granted provided that this copyright notice
  9.  * appears in all copies. Please refer to the file "copyright.html"
  10.  * for further important copyright and licensing information.
  11.  *
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
  13.  * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
  14.  * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
  15.  * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
  16.  * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
  17.  * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
  18.  */
  19. package java.awt;
  20.  
  21. import java.io.*;
  22. import java.lang.*;
  23. import java.util.*;
  24. import java.awt.image.ImageObserver;
  25.  
  26. /**
  27.  * Graphics is the abstract base class for all graphic 
  28.  * contexts for various devices. 
  29.  * 
  30.  * @version     1.30, 19 Mar 1996
  31.  * @author     Sami Shaio
  32.  * @author     Arthur van Hoff
  33.  */
  34. public abstract class Graphics {
  35.  
  36.     /**
  37.      * Constructs a new Graphics Object. Graphic contexts cannot be 
  38.      * created directly. They must be obtained from another graphics
  39.      * context or created by a Component.
  40.      * @see Component#getGraphics
  41.      * @see #create
  42.      */
  43.     protected Graphics() {
  44.     }
  45.  
  46.     /**
  47.      * Creates a new Graphics Object that is a copy of the original Graphics Object.
  48.      */
  49.     public abstract Graphics create();
  50.  
  51.     /**
  52.      * Creates a new Graphics Object with the specified parameters, based on the original
  53.      * Graphics Object. 
  54.      * This method translates the specified parameters, x and y, to
  55.      * the proper origin coordinates and then clips the Graphics Object to the
  56.      * area.
  57.      * @param x the x coordinate
  58.      * @param y the y coordinate
  59.      * @param width the width of the area
  60.      * @param height the height of the area
  61.      * @see #translate
  62.      */
  63.     public Graphics create(int x, int y, int width, int height) {
  64.     Graphics g = create();
  65.     g.translate(x, y);
  66.     g.clipRect(0, 0, width, height);
  67.     return g;
  68.     }
  69.  
  70.     /**
  71.      * Translates the specified parameters into the origin of the graphics context. All subsequent
  72.      * operations on this graphics context will be relative to this origin.
  73.      * @param x the x coordinate
  74.      * @param y the y coordinate
  75.      */
  76.     public abstract void translate(int x, int y);
  77.  
  78.     /**
  79.      * Gets the current color.
  80.      * @see #setColor
  81.      */
  82.     public abstract Color getColor();
  83.  
  84.     /**
  85.      * Sets the current color to the specified color. All subsequent graphics operations
  86.      * will use this specified color.
  87.      * @param c the color to be set
  88.      * @see Color
  89.      * @see #getColor
  90.      */
  91.     public abstract void setColor(Color c);
  92.  
  93.     /**
  94.      * Sets the paint mode to overwrite the destination with the
  95.      * current color. 
  96.      */
  97.     public abstract void setPaintMode();
  98.  
  99.     /**
  100.      * Sets the paint mode to alternate between the current color
  101.      * and the new specified color.  When drawing operations are
  102.      * performed, pixels which are the current color will be changed
  103.      * to the specified color and vice versa.  Pixels of colors other
  104.      * than those two colors will be changed in an unpredictable, but
  105.      * reversible manner - if you draw the same figure twice then all
  106.      * pixels will be restored to their original values.
  107.      * @param c1 the second color
  108.      */
  109.     public abstract void setXORMode(Color c1);
  110.  
  111.     /**
  112.      * Gets the current font.
  113.      * @see #setFont
  114.      */
  115.     public abstract Font getFont();
  116.  
  117.     /**
  118.      * Sets the font for all subsequent text-drawing operations.
  119.      * @param font the specified font
  120.      * @see Font
  121.      * @see #getFont
  122.      * @see #drawString
  123.      * @see #drawBytes
  124.      * @see #drawChars
  125.     */
  126.     public abstract void setFont(Font font);
  127.  
  128.     /**
  129.      * Gets the current font metrics.
  130.      * @see #getFont
  131.      */
  132.     public FontMetrics getFontMetrics() {
  133.     return getFontMetrics(getFont());
  134.     }
  135.  
  136.     /**
  137.      * Gets the current font metrics for the specified font.
  138.      * @param f the specified font
  139.      * @see #getFont
  140.      * @see #getFontMetrics
  141.      */
  142.     public abstract FontMetrics getFontMetrics(Font f);
  143.  
  144.  
  145.     /** 
  146.      * Returns the bounding rectangle of the current clipping area.
  147.      * @see #clipRect
  148.      */
  149.     public abstract Rectangle getClipRect();
  150.  
  151.     /** 
  152.      * Clips to a rectangle. The resulting clipping area is the
  153.      * intersection of the current clipping area and the specified
  154.      * rectangle. Graphic operations have no effect outside of the
  155.      * clipping area.
  156.      * @param x the x coordinate
  157.      * @param y the y coordinate
  158.      * @param width the width of the rectangle
  159.      * @param height the height of the rectangle
  160.      * @see #getClipRect
  161.      */
  162.     public abstract void clipRect(int x, int y, int width, int height);
  163.  
  164.     /**
  165.      * Copies an area of the screen.
  166.      * @param x the x-coordinate of the source
  167.      * @param y the y-coordinate of the source
  168.      * @param width the width
  169.      * @param height the height
  170.      * @param dx the horizontal distance
  171.      * @param dy the vertical distance
  172.      */
  173.     public abstract void copyArea(int x, int y, int width, int height, int dx, int dy);
  174.  
  175.     /** 
  176.      * Draws a line between the coordinates (x1,y1) and (x2,y2). The line is drawn
  177.      * below and to the left of the logical coordinates.
  178.      * @param x1 the first point's x coordinate
  179.      * @param y1 the first point's y coordinate
  180.      * @param x2 the second point's x coordinate
  181.      * @param y2 the second point's y coordinate
  182.      */
  183.     public abstract void drawLine(int x1, int y1, int x2, int y2);
  184.  
  185.     /** 
  186.      * Fills the specified rectangle with the current color. 
  187.      * @param x the x coordinate
  188.      * @param y the y coordinate
  189.      * @param width the width of the rectangle
  190.      * @param height the height of the rectangle
  191.      * @see #drawRect
  192.      * @see #clearRect
  193.      */
  194.     public abstract void fillRect(int x, int y, int width, int height);
  195.  
  196.     /** 
  197.      * Draws the outline of the specified rectangle using the current color.
  198.      * Use drawRect(x, y, width-1, height-1) to draw the outline inside the specified
  199.      * rectangle.
  200.      * @param x the x coordinate
  201.      * @param y the y coordinate
  202.      * @param width the width of the rectangle
  203.      * @param height the height of the rectangle
  204.      * @see #fillRect
  205.      * @see #clearRect
  206.      */
  207.     public void drawRect(int x, int y, int width, int height) {
  208.     drawLine(x, y, x + width, y);
  209.     drawLine(x + width, y, x + width, y + height);
  210.     drawLine(x, y, x, y + height);
  211.     drawLine(x, y + height, x + width, y + height);
  212.     }
  213.     
  214.     /** 
  215.      * Clears the specified rectangle by filling it with the current background color
  216.      * of the current drawing surface.
  217.      * Which drawing surface it selects depends on how the graphics context
  218.      * was created.
  219.      * @param x the x coordinate
  220.      * @param y the y coordinate
  221.      * @param width the width of the rectangle
  222.      * @param height the height of the rectangle
  223.      * @see #fillRect
  224.      * @see #drawRect
  225.      */
  226.     public abstract void clearRect(int x, int y, int width, int height);
  227.  
  228.     /** 
  229.      * Draws an outlined rounded corner rectangle using the current color.
  230.      * @param x the x coordinate
  231.      * @param y the y coordinate
  232.      * @param width the width of the rectangle
  233.      * @param height the height of the rectangle
  234.      * @param arcWidth the horizontal diameter of the arc at the four corners
  235.      * @param arcHeight the horizontal diameter of the arc at the four corners
  236.      * @see #fillRoundRect
  237.      */
  238.     public abstract void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  239.  
  240.     /** 
  241.      * Draws a rounded rectangle filled in with the current color.
  242.      * @param x the x coordinate
  243.      * @param y the y coordinate
  244.      * @param width the width of the rectangle
  245.      * @param height the height of the rectangle
  246.      * @param arcWidth the horizontal diameter of the arc at the four corners
  247.      * @param arcHeight the horizontal diameter of the arc at the four corners
  248.      * @see #drawRoundRect
  249.      */
  250.     public abstract void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  251.  
  252.     /**
  253.      * Draws a highlighted 3-D rectangle.
  254.      * @param x the x coordinate
  255.      * @param y the y coordinate
  256.      * @param width the width of the rectangle
  257.      * @param height the height of the rectangle
  258.      * @param raised a boolean that states whether the rectangle is raised or not
  259.      */
  260.     public void draw3DRect(int x, int y, int width, int height, boolean raised) {
  261.     Color c = getColor();
  262.     Color brighter = c.brighter();
  263.     Color darker = c.darker();
  264.  
  265.     setColor(raised ? brighter : darker);
  266.     drawLine(x, y, x, y + height);
  267.     drawLine(x + 1, y, x + width - 1, y);
  268.     setColor(raised ? darker : brighter);
  269.     drawLine(x + 1, y + height, x + width, y + height);
  270.     drawLine(x + width, y, x + width, y + height - 1);
  271.     setColor(c);
  272.     }    
  273.  
  274.     /**
  275.      * Paints a highlighted 3-D rectangle using the current color.
  276.      * @param x the x coordinate
  277.      * @param y the y coordinate
  278.      * @param width the width of the rectangle
  279.      * @param height the height of the rectangle
  280.      * @param raised a boolean that states whether the rectangle is raised or not
  281.      */
  282.     public void fill3DRect(int x, int y, int width, int height, boolean raised) {
  283.     Color c = getColor();
  284.     Color brighter = c.brighter();
  285.     Color darker = c.darker();
  286.  
  287.     if (!raised) {
  288.         setColor(darker);
  289.     }
  290.     fillRect(x+1, y+1, width-2, height-2);
  291.     setColor(raised ? brighter : darker);
  292.     drawLine(x, y, x, y + height - 1);
  293.     drawLine(x + 1, y, x + width - 2, y);
  294.     setColor(raised ? darker : brighter);
  295.     drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
  296.     drawLine(x + width - 1, y, x + width - 1, y + height - 2);
  297.     setColor(c);
  298.     }    
  299.  
  300.     /** 
  301.      * Draws an oval inside the specified rectangle using the current color.
  302.      * @param x the x coordinate
  303.      * @param y the y coordinate
  304.      * @param width the width of the rectangle
  305.      * @param height the height of the rectangle
  306.      * @see #fillOval
  307.      */
  308.     public abstract void drawOval(int x, int y, int width, int height);
  309.  
  310.     /** 
  311.      * Fills an oval inside the specified rectangle using the current color.
  312.      * @param x the x coordinate
  313.      * @param y the y coordinate
  314.      * @param width the width of the rectangle
  315.      * @param height the height of the rectangle
  316.      * @see #drawOval
  317.      */
  318.     public abstract void fillOval(int x, int y, int width, int height);
  319.  
  320.     /**
  321.      * Draws an arc bounded by the specified rectangle starting at
  322.      * startAngle, where 0 degrees is at the 3-o'clock position, and
  323.      * extending for arcAngle degrees.  Positive values for arcAngle
  324.      * indicate counter-clockwise rotations, negative values indicate
  325.      * clockwise rotations. 
  326.      * @param x the x coordinate
  327.      * @param y the y coordinate
  328.      * @param width the width of the rectangle
  329.      * @param height the height of the rectangle
  330.      * @param startAngle the beginning angle
  331.      * @param arcAngle the angle of the arc (relative to startAngle).
  332.      * @see #fillArc
  333.      */
  334.     public abstract void drawArc(int x, int y, int width, int height,
  335.                  int startAngle, int arcAngle);
  336.  
  337.     /** 
  338.      * Fills an arc using the current color. This generates a pie shape.
  339.      * The extent of the arc is the same as is described for the drawArc
  340.      * method.
  341.      * @param x the x coordinate
  342.      * @param y the y coordinate
  343.      * @param width the width of the arc
  344.      * @param height the height of the arc
  345.      * @param startAngle the beginning angle
  346.      * @param arcAngle the angle of the arc (relative to startAngle).
  347.      * @see #drawArc
  348.      */
  349.     public abstract void fillArc(int x, int y, int width, int height,
  350.                  int startAngle, int arcAngle);
  351.  
  352.     /** 
  353.      * Draws a polygon defined by an array of x points and y points.
  354.      * @param xPoints an array of x points
  355.      * @param yPoints an array of y points
  356.      * @param nPoints the total number of points
  357.      * @see #fillPolygon
  358.      */
  359.     public abstract void drawPolygon(int xPoints[], int yPoints[], int nPoints);
  360.  
  361.     /** 
  362.      * Draws a polygon defined by the specified point.
  363.      * @param p the specified polygon
  364.      * @see #fillPolygon
  365.      */
  366.     public void drawPolygon(Polygon p) {
  367.     drawPolygon(p.xpoints, p.ypoints, p.npoints);
  368.     }
  369.  
  370.     /** 
  371.      * Fills a polygon with the current color using an
  372.      * even-odd fill rule (otherwise known as an alternating rule).
  373.      * @param xPoints an array of x points
  374.      * @param yPoints an array of y points
  375.      * @param nPoints the total number of points
  376.      * @see #drawPolygon
  377.      */
  378.     public abstract void fillPolygon(int xPoints[], int yPoints[], int nPoints);
  379.  
  380.     /** 
  381.      * Fills the specified polygon with the current color using an
  382.      * even-odd fill rule (otherwise known as an alternating rule).
  383.      * @param p the polygon
  384.      * @see #drawPolygon
  385.      */
  386.     public void fillPolygon(Polygon p) {
  387.     fillPolygon(p.xpoints, p.ypoints, p.npoints);
  388.     }
  389.  
  390.     /** 
  391.      * Draws the specified String using the current font and color.
  392.      * The x,y position is the starting point of the baseline of the String.
  393.      * @param str the String to be drawn
  394.      * @param x the x coordinate
  395.      * @param y the y coordinate
  396.      * @see #drawChars
  397.      * @see #drawBytes
  398.      */
  399.     public abstract void drawString(String str, int x, int y);
  400.  
  401.     /** 
  402.      * Draws the specified characters using the current font and color.
  403.      * @param data the array of characters to be drawn
  404.      * @param offset the start offset in the data
  405.      * @param length the number of characters to be drawn
  406.      * @param x the x coordinate
  407.      * @param y the y coordinate
  408.      * @see #drawString
  409.      * @see #drawBytes
  410.      */
  411.     public void drawChars(char data[], int offset, int length, int x, int y) {
  412.     drawString(new String(data, offset, length), x, y);
  413.     }
  414.  
  415.     /** 
  416.      * Draws the specified bytes using the current font and color.
  417.      * @param data the data to be drawn
  418.      * @param offset the start offset in the data
  419.      * @param length the number of bytes that are drawn
  420.      * @param x the x coordinate
  421.      * @param y the y coordinate
  422.      * @see #drawString
  423.      * @see #drawChars
  424.      */
  425.     public void drawBytes(byte data[], int offset, int length, int x, int y) {
  426.     drawString(new String(data, 0, offset, length), x, y);
  427.     }
  428.  
  429.     /** 
  430.      * Draws the specified image at the specified coordinate (x, y). If the image is 
  431.      * incomplete the image observer will be notified later.
  432.      * @param img the specified image to be drawn
  433.      * @param x the x coordinate
  434.      * @param y the y coordinate
  435.      * @param observer notifies if the image is complete or not
  436.      * @see Image
  437.      * @see ImageObserver
  438.      */
  439.     public abstract boolean drawImage(Image img, int x, int y, 
  440.                       ImageObserver observer);
  441.  
  442.     /**
  443.      * Draws the specified image inside the specified rectangle. The image is
  444.      * scaled if necessary. If the image is incomplete the image observer will be
  445.      * notified later.
  446.      * @param img the specified image to be drawn
  447.      * @param x the x coordinate
  448.      * @param y the y coordinate
  449.      * @param width the width of the rectangle
  450.      * @param height the height of the rectangle
  451.      * @param observer notifies if the image is complete or not
  452.      * @see Image
  453.      * @see ImageObserver
  454.      */
  455.     public abstract boolean drawImage(Image img, int x, int y,
  456.                       int width, int height, 
  457.                       ImageObserver observer);
  458.     
  459.     /** 
  460.      * Draws the specified image at the specified coordinate (x, y),
  461.      * with the given solid background Color.  If the image is 
  462.      * incomplete the image observer will be notified later.
  463.      * @param img the specified image to be drawn
  464.      * @param x the x coordinate
  465.      * @param y the y coordinate
  466.      * @param observer notifies if the image is complete or not
  467.      * @see Image
  468.      * @see ImageObserver
  469.      */
  470.     public abstract boolean drawImage(Image img, int x, int y, 
  471.                       Color bgcolor,
  472.                       ImageObserver observer);
  473.  
  474.     /**
  475.      * Draws the specified image inside the specified rectangle,
  476.      * with the given solid background Color. The image is
  477.      * scaled if necessary. If the image is incomplete the image
  478.      * observer will be notified later.
  479.      * @param img the specified image to be drawn
  480.      * @param x the x coordinate
  481.      * @param y the y coordinate
  482.      * @param width the width of the rectangle
  483.      * @param height the height of the rectangle
  484.      * @param observer notifies if the image is complete or not
  485.      * @see Image
  486.      * @see ImageObserver
  487.      */
  488.     public abstract boolean drawImage(Image img, int x, int y,
  489.                       int width, int height, 
  490.                       Color bgcolor,
  491.                       ImageObserver observer);
  492.     
  493.     /**
  494.      * Disposes of this graphics context.  The Graphics context cannot be used after 
  495.      * being disposed of.
  496.      * @see #finalize
  497.      */
  498.     public abstract void dispose();
  499.  
  500.     /**
  501.      * Disposes of this graphics context once it is no longer referenced.
  502.      * @see #dispose
  503.      */
  504.     public void finalize() {
  505.     dispose();
  506.     }
  507.  
  508.     /**
  509.      * Returns a String object representing this Graphic's value.
  510.      */
  511.     public String toString() {    
  512.     return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
  513.     }
  514.  
  515. }
  516.