Creating the jpr.lightweight Package From this point on, this chapter gets a bit code heavy. The javadoc comments take up a lot of space, but you will see that the end result is well worth the effort. Not just so you have documentation for the jpr.lightweight package, but also because you will get a good feel for creating your own documentation while you copy the source files. Creating the JPRComponent3D Class Here is the source code listing for the first class you’re going to create for the jpr.lightweight package, JPRComponent (by the way, jpr doesn’t really stand for anything, they’re just my initials). package jpr.lightweight; import java.awt.*; /** * A LightWeight component whose borders can be drawn to * make itself look sunk, raised, or flat. * @author Joseph P. Russell * @version 1.0 */ public abstract class JPRComponent3D extends Component { /** * Indicates to draw this component flat (not raised or sunk). * An "etched" border will be drawn but will appear flat. */ public final static int FLAT = 0; /** * Indicates to draw this component to appear raised from its parent. */ public final static int RAISED = 1; /** * Indicates to draw this component to appear to be sunk into its * parent. */ public final static int SUNK = 2; /** * The width of the edges. */ protected int magnitude; //where magnitude is 1 and inner area is only one pixel: protected final static int ABSOLUTE_MIN_WIDTH = 5; protected final static int ABSOLUTE_MIN_HEIGHT = 5; protected int current_appearance; protected Color shadow, dkshadow, highlight, lthighlight; /** * The color to be used as the control color. This color will affect * the other colors used to make the component appear to be three 438 J a v a P r o g r am m i n g f o r t h e A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 438 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. * dimensional. The default value is * <code>java.awt.SystemColor.control</code>. */ protected Color control; /** * Gets the appearance of this <code>JPRComponent3D</code>. * * @return The appearance of this <code>JPRComponent3D</code>. */ public int getAppearance() { return current_appearance; } /** * Sets the magnitude for this <code>JPRComponent3D</code>. * It controls how deep or raised it looks. * @param thick The magnitude of projection. */ public void setMagnitude(int thick) { magnitude = thick > 0 ? thick : magnitude; } /** * Gets the magnitude of this <code>JPRComponent3D</code>. * @return The magnitude of this <code>JPRComponent3D</code>. */ public int getMagnitude() { return magnitude; } /** * Overrides <code>java.awt.Component.getMinimumSize</code> to * ensure room for at least one pixel in the center of the borders. * @return the minimum size, taking into account the magnitude and * allows for at least one pixel in the center. */ public Dimension getMinimumSize() { int min_wh; min_wh = magnitude * 4 + 1; return new Dimension(min_wh, min_wh); } /** * Overrides <code>java.awt.Component.getPreferredSize()</code> * to return the current size. * @return the preferred size. */ public Dimension getPreferredSize() { return getSize(); } 439 C h a p t e r 12 C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 439 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. /** * Returns <code>true</code>. * @return <code>true</code>. */ public boolean isLightweight() { return true; } /** * Sets the color to be used as the base color and also sets the * colors used for shading and lighting effects. If the parameter * is <code>java.awt.SystemColor.control</code>, then the shading * and lighting colors will be set to the colors defined in the * system. If it is any other color, then the shading and lighting * colors will be different shades of the given color. * @param base_color The color to be used as the base color. */ public void setControlColor(Color base_color) { if (base_color == null) return; control = base_color; if (base_color == SystemColor.control) { shadow = SystemColor.controlShadow; dkshadow = SystemColor.controlDkShadow; highlight = SystemColor.controlHighlight; lthighlight = SystemColor.controlLtHighlight; } else { shadow = base_color.darker().darker(); dkshadow = shadow.darker().darker(); highlight = base_color; lthighlight = highlight.brighter().brighter(); } } /** * Sets the appearance of this <code>JPRComponent3D</code> to * the given style. * @param appearance. * Appearances may be {@link #FLAT FLAT}, {@link #RAISED RAISED}, * or {@link #SUNK SUNK}. */ public void setAppearance(int appearance) { if (appearance != SUNK && appearance != FLAT && appearance != RAISED) current_appearance = FLAT; else current_appearance = appearance; } /** * Sets the color used for highlighting effects to the given color. * @param hl The color to be used for highlighting effects. */ public void setHighlightColor(Color hl) { if (hl != null) highlight = hl; } 440 J a v a P r o g r am m i n g f o r t h e A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 440 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. /** * Sets the color used for light highlighting effects to the * given color. * @param lhl The color to be used for light highlighting effects. */ public void setLtHighlightColor(Color lhl) { if (lhl != null) lthighlight = lhl; } /** * Sets the color used for shading effects to the given color. * @param shade The color to be used for shading effects. */ public void setShadowColor(Color shade) { if (shade != null) shadow = shade; } /** * Sets the color used for dark shading effects to the given color. * @param dkshade The color to be used for dark shading effects. */ public void setDkShadowColor(Color dkshade) { if (dkshade != null) dkshadow = dkshade; } /** * Gets the color used for the control color * @return The color used for the control color. */ public Color getControlColor() { return control; } /** * Gets the color used for highlighting effects. * @return The color used for highlighting effects. */ public Color getHighlightColor() { return highlight; } /** * Gets the color used for light highlighting effects. * @return The color used for light highlighting effects. */ public Color getLtHighlightColor() { return lthighlight; } /** * Gets the color used for shading effects. * @return the color used for shading effects. */ 441 C h a p t e r 12 C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 441 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. public Color getShadowColor() { return shadow; } /** * Gets the color used for dark shading effects. * @return the color used for dark shading effects. */ public Color getDkShadowColor() { return dkshadow; } /** * Results in a call to {@link #paintFlat(Graphics) paintFlat}, * {@link #paintRaised paintRaised(Graphics) paintRaised}, * or {@link #paintSunk(Graphics) paintSunk}, depending on appearance. */ public void paint(Graphics g) { switch (current_appearance) { case FLAT: paintFlat(g); break; case RAISED: paintRaised(g); break; case SUNK: paintSunk(g); break; } } /** * Paints this <code>JPRComponent3D</code>'s {@link #FLAT FLAT} * appearance. */ public abstract void paintFlat(Graphics g); /** * Paints this <code>JPRComponent3D</code>'s {@link #RAISED RAISED} * appearance. */ public abstract void paintRaised(Graphics g); /** * Paints this <code>JPRComponent3D</code>'s {@link #SUNK SUNK} * appearance. */ public abstract void paintSunk(Graphics g); } 442 J a v a P r o g r am m i n g f o r t h e A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 442 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. The first thing to notice is the package declaration: package jpr.lightweight; Basically, all its members specify the current appearance of the JPRComponent3D object. RAISED, SUNK, and FLAT are static constants that describe how this JPRCom- ponent3D should be painted. The different Color members actually render the JPRComponent3D. There are five of them. control is the basic control color. The other colors are based off of this color. There are two highlight colors, highlight and lthighlight, and two shadow colors shadow and dkshadow. If these colors are all different shades of the same color, they can be used effec- tively to give the appearance of a three-dimensional component, but you can leave that up to subclasses of JPRComponent3D. This is an abstract class and doesn’t define the methods paintRaised(Graphics), paintSunk(Graphics), or paint- Flat(Graphics) . It just declares them abstract. Subclasses of this component can be any shape, so it is up to them to paint themselves. It does define the paint(Graphics) method, though. What it does is check the current_appearance variable to see if it’s raised, sunk, or flat and calls the corresponding paint… method. The get and set methods are fairly straight-forward. Other methods that need some explanation are isLightWeight(), which returns a boolean value, I just overrode it here to return true because this and its subclasses are lightweight components. The setControlColor(Color) method also needs a bit of an expla- nation. You see, if the parameter passed in to this method is SystemColor.con- trol , it uses the following color scheme: shadow = SystemColor.controlShadow; dkshadow = SystemColor.controlDkShadow; highlight = SystemColor.controlHighlight; lthighlight = SystemColor.controlLtHighlight; These colors define the colors that you have set for your operating system’s GUI. As an example in Windows, if you right-click the desktop, go to Properties, and then Appearance, you can choose a color scheme for your GUI. You can even go as far as specifying your own custom scheme. So the SystemColor colors specify these colors and if you want to maintain the look of your operating system (at least as far as color is concerned), pass in SystemColor.control as the argument to this method. On the other hand, if a different color is passed in, it attempts to create appropriate highlighting and shadowing colors by making use of the brighter() and darker() methods of the Color class. If you don’t like the defaults, you can just use the set… methods to explicitly set any colors. 443 C h a p t e r 12 C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 443 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. Creating the JPRRectComponent3D Class The JPRRectComponent3D class extends the JPRComponent3D class. It is also an abstract class, although it implements all the methods that were declared to be abstract in its superclass JPRComponent3D. The reason why it’s still abstract is because it has no actual use other than to provide basic functionality for other components to expand on. You can’t do anything with a JPRRectComponent3D except for painting it graphi- cally, so making it abstract here prevents any other classes from creating instances of this useless class; that is, useless to non-subclasses. It can come in handy for creating subclasses such as components that act like buttons, which appear raised until they are clicked and then they appear sunk and pop back up again after you release the mouse button. Another good use is for a text field or text area component that appears sunk and possibly has a white background and a cursor in the inside and listens for key events. There is a good base for functionality that can be very useful and should be reusable, but is not very useful by itself. This is a perfect example of the use- fulness of abstract classes. This is how robust, reusable, highly customizable packages are created in the real world. Here is the source code for JPRRectCompo- nent3D.java : package jpr.lightweight; import java.awt.*; /** * A LightWeight 3D rectangular component. * @author Joseph P. Russell * @version 1.0 */ public abstract class JPRRectComponent3D extends JPRComponent3D { /** * Constructs a <code>JPRRectComponent3D</code> using all default * settings. The default appearance is * {@link #FLAT FLAT}, the default size is the * minimum size, and the default magnitude is <code>1</code>. */ public JPRRectComponent3D() { this(ABSOLUTE_MIN_WIDTH, ABSOLUTE_MIN_HEIGHT, FLAT, 1); } /** * Constructs a <code>JPRRectComponent3D</code> with the given * dimensions. The default appearance is * {@link #FLAT FLAT} and the default magnitude is <code>1</code>. * @param wide the overall width * @param high the overall height */ 444 J a v a P r o g r am m i n g f o r t h e A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 444 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. public JPRRectComponent3D(int wide, int high) { this(wide, high, FLAT, 1); } /** * Constructs a <code>JPRRectComponent3D</code> with the given * appearance, using minimum size and a magnitude of <code>1</code>. * @param appearance The appearance. * Appearances may be {@link #FLAT FLAT}, {@link #RAISED RAISED}, * or {@link #SUNK SUNK}. */ public JPRRectComponent3D(int appearance) { this(ABSOLUTE_MIN_WIDTH, ABSOLUTE_MIN_HEIGHT, appearance, 1); } /** * Constructs a <code>JPRRectComponent3D</code> with the given * dimensions and appearance. The default magnitude is <code>1</code>. * @param wide the overall width. * @param high the overall height. * @param appearance The appearance. * Appearances may be {@link #FLAT FLAT}, {@link #RAISED RAISED}, * or {@link #SUNK SUNK}. */ public JPRRectComponent3D(int wide, int high, int appearance) { this(wide, high, appearance, 1); } /** * Constructs a <code>JPRRectComponent3D</code> with the given * dimensions, appearance, and magnitude. * @param wide the overall width. * @param high the overall height. * @param appearance The appearance. * Appearances may be {@link #FLAT FLAT}, {@link #RAISED RAISED}, * or {@link #SUNK SUNK}. * @param border_magnitude The thickness of the border. The larger * it is, the more deep or raised it appears. If the appearance is * {@link #FLAT FLAT}, then it won't look deeper or higher, but it * will have a thicker border. The actual pixel thickness is twice * that of the magnitude since there are two different-colored * rows of pixels around the border to enhance the three * dimensional look. */ public JPRRectComponent3D(int wide, int high, int appearance, int border_magnitude) { super(); if (wide < ABSOLUTE_MIN_WIDTH) wide = ABSOLUTE_MIN_WIDTH; if (high < ABSOLUTE_MIN_HEIGHT) high = ABSOLUTE_MIN_HEIGHT; setAppearance(appearance); setMagnitude(border_magnitude); setSize(wide, high); setControlColor(SystemColor.control); 445 C h a p t e r 12 C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 445 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. setBackground(SystemColor.control); setForeground(Color.black); } /** * Gets the size of the interior portion. * The interior portion is in the center, surrounded by the border. * @return The Dimension of the interior portion. */ public Dimension getInteriorSize() { return new Dimension(getSize().width - (4 * magnitude), getSize().height - (4 * magnitude)); } public void paint(Graphics g) { g.setColor(getBackground()); g.fillRect(0, 0, getSize().width, getSize().height); super.paint(g); } public void paintFlat(Graphics g) { g.setColor(lthighlight); g.fillRect(0, 0, getSize().width, getSize().height); g.setColor(shadow); g.fillRect(0, 0, magnitude, getSize().height); g.fillRect(magnitude, 0, getSize().width - magnitude, magnitude); for (int i = 0; i < magnitude; i++) { g.drawRect(magnitude * 2 + i, magnitude * 2 + i, getInteriorSize().width, getInteriorSize().height); } g.setColor(getBackground()); g.fillRect(magnitude * 2, magnitude * 2, getInteriorSize().width, getInteriorSize().height); } public void paintRaised(Graphics g) { g.setColor(lthighlight); for (int i = 0; i < magnitude * 2; i++) { if (i == ((magnitude * 2) - 1)) g.setColor(highlight); g.drawLine(i, i, getSize().width - (i + 2), i); g.drawLine(i, 1+i, i, getSize().height - (i + 2)); } g.setColor(dkshadow); for (int i = 0; i < magnitude * 2; i++) { if (i > 0) g.setColor(shadow); g.drawLine(i, getSize().height - (i + 1), getSize().width - (i + 1), getSize().height - (i + 1)); g.drawLine(getSize().width - (i + 1), i, getSize().width - (i + 1), getSize().height - (i + 2)); } } 446 J a v a P r o g r am m i n g f o r t h e A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 446 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. public void paintSunk(Graphics g) { for (int i = 0; i < magnitude * 2; i++) { if (i == ((magnitude * 2) - 1)) g.setColor(dkshadow); else g.setColor(shadow); g.drawLine(i, i, getSize().width - (i + 2), i); g.drawLine(i, 1+i, i, getSize().height - (i + 2)); } for (int i = 0; i < magnitude * 2; i++) { if (i == ((magnitude * 2) - 1)) g.setColor(highlight); else g.setColor(lthighlight); g.drawLine(getSize().width - (i + 1), i, getSize().width - (i + 1), getSize().height - (i + 2)); g.drawLine(i, getSize().height - (i + 1), getSize().width - (i + 1), getSize().height - (i + 1)); } } } This class provides a good number of constructors for specifying its initial state. Other than that, the most significant code in this program is the implementa- tions of the different paint… methods. The paint(Graphics) method is overrid- den to clear the background with the background color, and then it calls its superclass’s paint(Graphics) method which just calls one of the three methods for rendering its current appearance. The three methods can seem a bit complicated at first, but basically what they’re doing is painting lines that make the appearance look three-dimensional and represent the state of being RAISED, SUNK, or FLAT. In general, highlighted colors on the top and left of the shapes and the darker shadow colors on the bottom and right make it appear to be raised and reversed, it appears to be sunk. The FLAT appearance is drawn so that the border around the JPRRectComponent3D appears to be etched and the surface appears to be at the same level as its container. The magnitude variable specifies the degree of dimension (how much it is raised or sunk, or how deep and wide the etched border is around the FLAT appearance). Another thing it provides is the getInteriorSize() method, which returns a Dimension object that represents the size of the interior portion of the JPRRect- Component3D . It calculates this value by subtracting four times the magnitude from the width and the height because the magnitude is half the width of the bor- der (so it can paint at least two colors given a magnitude of one). This means that the border takes up twice the width of the magnitude on all four sides of the JPRRectComponent3D. 447 C h a p t e r 12 C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 447 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. [...]... e.getModifiers())); JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 452 Java Programming for the Absolute Beginner 452 FIGURE 12.4 Clicking any of the links brings you to detailed information about the jpr.lightweight thing that you clicked TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 453 453... you specified using the javadoc comments FIGURE 12.3 The javadoc utility in action TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark Creating Your Own Components and Packages Generating the Documentation for jpr.lightweight Chapter 12 ActionEvent.ACTION_PERFORMED, actionCommand, e.getModifiers())); JavaProgAbsBeg-12.qxd 2/25/03... actionListener.actionPerformed(new ActionEvent(this, ActionEvent.ACTION_PERFORMED, actionCommand, e.getModifiers())); } } break; } } super.processMouseEvent(e); } Chapter 12 public JPRButton3D(int wide, int high, int border_magnitude) { super(wide, high, RAISED, border_magnitude); enableEvents(AWTEvent.MOUSE_EVENT_MASK); } JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 450 Java Programming for the Absolute Beginner... actionListener.actionPerformed(new ActionEvent(this, TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 451 451 Which results in the AWTEventMulticaster informing all registered listeners of the event It provides the addActionListener(ActionListener) and removeActionListener(ActionListener) methods for. .. and Packages • MineCellListener provides an interface for other classes to listen to MineCellEvents Chapter 12 The classes that make up the functionality of the mine cells are the following: JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 456 456 Java Programming for the Absolute Beginner The MineCellListener Interface MineCellListener is an interface for listening to the four types of mine cell events The... ActionListener It keeps track of four JPRButton3Ds in an array, b[] It constructs the first button, b[0] passing JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 454 Java Programming for the Absolute Beginner 454 public static void main(String args[]) { new JPRButton3DTest(); } public void actionPerformed(ActionEvent e) { System.out.println(e); if (e.getSource() == b[0]) { System.out.println("Tiny Button");...JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 448 448 Java Programming for the Absolute Beginner Creating the JPRButton3D Class The JPRButton3D class is the only non-abstract class that you’re going to be defining for the jpr.lightweight package It extends the JPRRectComponent class and adds functionality that... Listens for when mine cells are revealed mineCellFlagged(MineCellEvent) Listens for when mine cells are flagged mineCellUnflagged(MineCellEvent) Listens for when mine cells are unflagged mineCellDetonated(MineCellEvent) Listens for when mine cells are detonated As with most interfaces, the listing is extremely quick and to the point Here it is: /* * MineCellListener * Interface for listening for MineCellEvents... documentation by using the javadoc utility First make sure you’re in the directory that contains the jpr subdirectory and that the jpr directory has the lightweight subdirectory in it, which contains the class files for the java. lightweight package Also, before you do this, create a new subdirectory of the current directory called jprdoc Now at the command prompt, type: javadoc –d jprdoc –author -version... the top shows the second JPRButton3D before it is disabled and the image on the bottom shows it after it is disabled FIGURE 12.5 Yup, the buttons seem like they’re working okay Clicking them really looks like they’re being pressed down! TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM . A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 438 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. *. C r e a t i n g Y o u r O w n C o m p o n e n t s a n d P a c k a g e s JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 439 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. /** *. A b s o l ut e B e gi n n e r JavaProgAbsBeg-12.qxd 2/25/03 8:58 AM Page 440 TEAM LinG - Live, Informative, Non-cost and Genuine! Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark. /** *