home *** CD-ROM | disk | FTP | other *** search
/ Java Programmer's Toolkit / Java Programmer's Toolkit.iso / solaris2 / jdk / src / java / awt / graphics.jav < prev    next >
Encoding:
Text File  |  1995-10-30  |  15.5 KB  |  481 lines
  1. /*
  2.  * @(#)Graphics.java    1.23 95/09/18 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.23, 09/18/95
  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 either a component can create them.
  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.      * @see #scale
  76.      */
  77.     public abstract void translate(int x, int y);
  78.  
  79.     /**
  80.      * Scales the graphics context. All subsequent operations on this
  81.      * graphics context will be affected.
  82.      * @param sx the scaled x coordinate
  83.      * @param sy the scaled y coordinate
  84.      * @see #translate
  85.      */
  86.     public abstract void scale(float sx, float sy);
  87.  
  88.     /**
  89.      * Gets the current color.
  90.      * @see #setColor
  91.      */
  92.     public abstract Color getColor();
  93.  
  94.     /**
  95.      * Sets the current color to the specified color. All subsequent graphics operations
  96.      * will use this specified color.
  97.      * @param c the color to be set
  98.      * @see Color
  99.      * @see #getColor
  100.      */
  101.     public abstract void setColor(Color c);
  102.  
  103.     /**
  104.      * Sets the default paint mode to overwrite the destination with the
  105.      * current color. 
  106.      */
  107.     public abstract void setPaintMode();
  108.  
  109.     /**
  110.      * Sets the paint mode to alternate between the current color
  111.      * and the new specified color.
  112.      * @param c1 the second color
  113.      */
  114.     public abstract void setXORMode(Color c1);
  115.  
  116.     /**
  117.      * Gets the current font.
  118.      * @see #setFont
  119.      */
  120.     public abstract Font getFont();
  121.  
  122.     /**
  123.      * Sets the font for all subsequent text-drawing operations.
  124.      * @param font the specified font
  125.      * @see Font
  126.      * @see #getFont
  127.      * @see #drawString
  128.      * @see #drawBytes
  129.      * @see #drawChars
  130.     */
  131.     public abstract void setFont(Font font);
  132.  
  133.     /**
  134.      * Gets the current font metrics.
  135.      * @see #getFont
  136.      */
  137.     public FontMetrics getFontMetrics() {
  138.     return getFontMetrics(getFont());
  139.     }
  140.  
  141.     /**
  142.      * Gets the current font metrics for the specified font.
  143.      * @param f the specified font
  144.      * @see #getFont
  145.      * @see #getFontMetrics
  146.      */
  147.     public abstract FontMetrics getFontMetrics(Font f);
  148.  
  149.  
  150.     /** 
  151.      * Returns the bounding rectangle of the current clipping area.
  152.      * @see #clipRect
  153.      */
  154.     public abstract Rectangle getClipRect();
  155.  
  156.     /** 
  157.      * Clips to a rectangle. The resulting clipping area is the
  158.      * intersection of the current clipping area and the specified
  159.      * rectangle. Graphic operations have no effect outside of the
  160.      * clipping area.
  161.      * @param x the x coordinate
  162.      * @param y the y coordinate
  163.      * @param width the width of the rectangle
  164.      * @param height the height of the rectangle
  165.      * @see #getClipRect
  166.      */
  167.     public abstract void clipRect(int x, int y, int width, int height);
  168.  
  169.     /**
  170.      * Copies an area of the screen.
  171.      * @param x the x-coordinate of the source
  172.      * @param y the y-coordinate of the source
  173.      * @param width the width
  174.      * @param height the height
  175.      * @param dx the horizontal distance
  176.      * @param dy the vertical distance
  177.      */
  178.     public abstract void copyArea(int x, int y, int width, int height, int dx, int dy);
  179.  
  180.     /** 
  181.      * Draws a line between the coordinates (x1,y1) and (x2,y2). The line is drawn
  182.      * below and to the left of the logical coordinates.
  183.      * @param x1 the first point's x coordinate
  184.      * @param y1 the first point's y coordinate
  185.      * @param x2 the second point's x coordinate
  186.      * @param y2 the second point's y coordinate
  187.      */
  188.     public abstract void drawLine(int x1, int y1, int x2, int y2);
  189.  
  190.     /** 
  191.      * Fills the specified rectangle with the current color. 
  192.      * @param x the x coordinate
  193.      * @param y the y coordinate
  194.      * @param width the width of the rectangle
  195.      * @param height the height of the rectangle
  196.      * @see #drawRect
  197.      * @see #clearRect
  198.      */
  199.     public abstract void fillRect(int x, int y, int width, int height);
  200.  
  201.     /** 
  202.      * Draws the outline of the specified rectangle using the current color.
  203.      * Use drawRect(x, y, width-1, height-1) to draw the outline inside the specified
  204.      * rectangle.
  205.      * @param x the x coordinate
  206.      * @param y the y coordinate
  207.      * @param width the width of the rectangle
  208.      * @param height the height of the rectangle
  209.      * @see #fillRect
  210.      * @see #clearRect
  211.      */
  212.     public void drawRect(int x, int y, int width, int height) {
  213.     drawLine(x, y, x + width, y);
  214.     drawLine(x + width, y, x + width, y + height);
  215.     drawLine(x, y, x, y + height);
  216.     drawLine(x, y + height, x + width, y + height);
  217.     }
  218.     
  219.     /** 
  220.      * Clears the specified rectangle by filling it with the current background color
  221.      * of the current drawing surface.
  222.      * Which drawing surface it selects depends on how the graphics context
  223.      * was created.
  224.      * @param x the x coordinate
  225.      * @param y the y coordinate
  226.      * @param width the width of the rectangle
  227.      * @param height the height of the rectangle
  228.      * @see #fillRect
  229.      * @see #drawRect
  230.      */
  231.     public abstract void clearRect(int x, int y, int width, int height);
  232.  
  233.     /** 
  234.      * Draws an outlined rounded corner rectangle using the current color.
  235.      * @param x the x coordinate
  236.      * @param y the y coordinate
  237.      * @param width the width of the rectangle
  238.      * @param height the height of the rectangle
  239.      * @param arcWidth the diameter of the arc
  240.      * @param arcHeight the radius of the arc
  241.      * @see #fillRoundRect
  242.      */
  243.     public abstract void drawRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  244.  
  245.     /** 
  246.      * Draws a rounded rectangle filled in with the current color.
  247.      * @param x the x coordinate
  248.      * @param y the y coordinate
  249.      * @param width the width of the rectangle
  250.      * @param height the height of the rectangle
  251.      * @param arcWidth the diameter of the arc
  252.      * @param arcHeight the radius of the arc
  253.      * @see #drawRoundRect
  254.      */
  255.     public abstract void fillRoundRect(int x, int y, int width, int height, int arcWidth, int arcHeight);
  256.  
  257.     /**
  258.      * Draws a highlighted 3-D rectangle.
  259.      * @param x the x coordinate
  260.      * @param y the y coordinate
  261.      * @param width the width of the rectangle
  262.      * @param height the height of the rectangle
  263.      * @param raised a boolean that states whether the rectangle is raised or not
  264.      */
  265.     public void draw3DRect(int x, int y, int width, int height, boolean raised) {
  266.     Color c = getColor();
  267.     Color brighter = c.brighter();
  268.     Color darker = c.darker();
  269.  
  270.     setColor(raised ? brighter : darker);
  271.     drawLine(x, y, x, y + height);
  272.     drawLine(x + 1, y, x + width - 1, y);
  273.     setColor(raised ? darker : brighter);
  274.     drawLine(x + 1, y + height, x + width, y + height);
  275.     drawLine(x + width, y, x + width, y + height);
  276.     setColor(c);
  277.     }    
  278.  
  279.     /**
  280.      * Paints a highlighted 3-D rectangle using the current color.
  281.      * @param x the x coordinate
  282.      * @param y the y coordinate
  283.      * @param width the width of the rectangle
  284.      * @param height the height of the rectangle
  285.      * @param raised a boolean that states whether the rectangle is raised or not
  286.      */
  287.     public void fill3DRect(int x, int y, int width, int height, boolean raised) {
  288.     Color c = getColor();
  289.     Color brighter = c.brighter();
  290.     Color darker = c.darker();
  291.  
  292.     if (!raised) {
  293.         setColor(darker);
  294.     }
  295.     fillRect(x+1, y+1, width-2, height-2);
  296.     setColor(raised ? brighter : darker);
  297.     drawLine(x, y, x, y + height - 1);
  298.     drawLine(x + 1, y, x + width - 2, y);
  299.     setColor(raised ? darker : brighter);
  300.     drawLine(x + 1, y + height - 1, x + width - 1, y + height - 1);
  301.     drawLine(x + width - 1, y, x + width - 1, y + height - 1);
  302.     setColor(c);
  303.     }    
  304.  
  305.     /** 
  306.      * Draws an oval inside the specified rectangle using the current color.
  307.      * @param x the x coordinate
  308.      * @param y the y coordinate
  309.      * @param width the width of the rectangle
  310.      * @param height the height of the rectangle
  311.      * @see #fillOval
  312.      */
  313.     public abstract void drawOval(int x, int y, int width, int height);
  314.  
  315.     /** 
  316.      * Fills an oval inside the specified rectangle using the current color.
  317.      * @param x the x coordinate
  318.      * @param y the y coordinate
  319.      * @param width the width of the rectangle
  320.      * @param height the height of the rectangle
  321.      * @see #drawOval
  322.      */
  323.     public abstract void fillOval(int x, int y, int width, int height);
  324.  
  325.     /**
  326.      * Draws an arc bounded by the specified rectangle from startAngle to
  327.      * endAngle. 0 degrees is at the 3-o'clock position.Positive arc
  328.      * angles indicate counter-clockwise rotations, negative arc angles are
  329.      * drawn clockwise. 
  330.      * @param x the x coordinate
  331.      * @param y the y coordinate
  332.      * @param width the width of the rectangle
  333.      * @param height the height of the rectangle
  334.      * @param startAngle the beginning angle
  335.      * @param arcAngle the angle of the arc (relative to startAngle).
  336.      * @see #fillArc
  337.      */
  338.     public abstract void drawArc(int x, int y, int width, int height, int startAngle, int arcAngle);
  339.  
  340.     /** 
  341.      * Fills an arc using the current color. This generates a pie shape.
  342.      *
  343.      * @param x the x coordinate
  344.      * @param y the y coordinate
  345.      * @param width the width of the arc
  346.      * @param height the height of the arc
  347.      * @param startAngle the beginning angle
  348.      * @param arcAngle the angle of the arc (relative to startAngle).
  349.      * @see #drawArc
  350.      */
  351.     public abstract void fillArc(int x, int y, int width, int height, int startAngle, int arcAngle);
  352.  
  353.     /** 
  354.      * Draws a polygon defined by an array of x points and y points.
  355.      * @param xPoints an array of x points
  356.      * @param yPoints an array of y points
  357.      * @param nPoints the total number of points
  358.      * @see #fillPolygon
  359.      */
  360.     public abstract void drawPolygon(int xPoints[], int yPoints[], int nPoints);
  361.  
  362.     /** 
  363.      * Draws a polygon defined by the specified point.
  364.      * @param p the specified polygon
  365.      * @see #fillPolygon
  366.      */
  367.     public void drawPolygon(Polygon p) {
  368.     drawPolygon(p.xpoints, p.ypoints, p.npoints);
  369.     }
  370.  
  371.     /** 
  372.      * Fills a polygon with the current color.
  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.
  382.      * @param p the polygon
  383.      * @see #drawPolygon
  384.      */
  385.     public void fillPolygon(Polygon p) {
  386.     fillPolygon(p.xpoints, p.ypoints, p.npoints);
  387.     }
  388.  
  389.     /** 
  390.      * Draws the specified String using the current font and color.
  391.      * The x,y position is the starting point of the baseline of the String.
  392.      * @param str the String to be drawn
  393.      * @param x the x coordinate
  394.      * @param y the y coordinate
  395.      * @see #drawChars
  396.      * @see #drawBytes
  397.      */
  398.     public abstract void drawString(String str, int x, int y);
  399.  
  400.     /** 
  401.      * Draws the specified characters using the current font and color.
  402.      * @param data the array of characters to be drawn
  403.      * @param offset the start offset in the data
  404.      * @param length the number of characters to be drawn
  405.      * @param x the x coordinate
  406.      * @param y the y coordinate
  407.      * @see #drawString
  408.      * @see #drawBytes
  409.      */
  410.     public void drawChars(char data[], int offset, int length, int x, int y) {
  411.     drawString(new String(data, offset, length), x, y);
  412.     }
  413.  
  414.     /** 
  415.      * Draws the specified bytes using the current font and color.
  416.      * @param data the data to be drawn
  417.      * @param offset the start offset in the data
  418.      * @param length the number of bytes that are drawn
  419.      * @param x the x coordinate
  420.      * @param y the y coordinate
  421.      * @see #drawString
  422.      * @see #drawChars
  423.      */
  424.     public void drawBytes(byte data[], int offset, int length, int x, int y) {
  425.     drawString(new String(data, 0, offset, length), x, y);
  426.     }
  427.  
  428.     /** 
  429.      * Draws the specified image at the specified coordinate (x, y). If the image is 
  430.      * incomplete the image observer will be notified later.
  431.      * @param img the specified image to be drawn
  432.      * @param x the x coordinate
  433.      * @param y the y coordinate
  434.      * @param observer notifies if the image is complete or not
  435.      * @see Image
  436.      * @see ImageObserver
  437.      */
  438.     public abstract boolean drawImage(Image img, int x, int y, 
  439.                       ImageObserver observer);
  440.  
  441.     /**
  442.      * Draws the specified image inside the specified rectangle. The image is
  443.      * scaled if necessary. If the image is incomplete the image observer will be
  444.      * notified later.
  445.      * @param img the specified image to be drawn
  446.      * @param x the x coordinate
  447.      * @param y the y coordinate
  448.      * @param width the width of the rectangle
  449.      * @param height the height of the rectangle
  450.      * @param observer notifies if the image is complete or not
  451.      * @see Image
  452.      * @see ImageObserver
  453.      */
  454.     public abstract boolean drawImage(Image img, int x, int y,
  455.                       int width, int height, 
  456.                       ImageObserver observer);
  457.     
  458.     /**
  459.      * Disposes of this graphics context.  The Graphics context cannot be used after 
  460.      * being disposed of.
  461.      * @see #finalize
  462.      */
  463.     public abstract void dispose();
  464.  
  465.     /**
  466.      * Disposes of this graphics context once it is no longer referenced.
  467.      * @see #dispose
  468.      */
  469.     public void finalize() {
  470.     dispose();
  471.     }
  472.  
  473.     /**
  474.      * Returns a String object representing this Graphic's value.
  475.      */
  476.     public String toString() {    
  477.     return getClass().getName() + "[font=" + getFont() + ",color=" + getColor() + "]";
  478.     }
  479.  
  480. }
  481.