(If you aren't looking at the HTML version of this file, you won't be able to see the picture) This program demonstrates some important features of graphics programming. Specifically, it demonstrates some simple methods to speed the program up so that the screen is updated smoothly, without too much flicker. This is particularly important in Java applets, which never run particularly fast. The clock display is updated once every second. This involves redrawing the `hands' of the clock. However, to give the impression that the hands are `moving', we must first erase the hand from the old position. So every second the following actions occur: 1. Find out the current time (hours, minutes and seconds) 2. Calculate the position of the clock hands for the _previous_ time (NOT the current time) 3. Draw the clock hands in these positions, but with the colour set to white (i.e., erase the hands). 4. Draw the clock hands in the new position, with colour set to something visible (I have chosen blue and black) 5. Save the current time as the `previous' time, so that when we get back to step 1, it will erase the hands correctly. This process is the basis of smooth animation: calculate everything before drawing anything. If there is too much time between the erase operation and the draw operation, the screen will flicker every time it is updated, which looks very ugly. This applet creates a separate `thread of execution' for itself. This technique will be covered in week 10, so don't worry if you don't understand it yet. You should still be able to follow almost all of this program. Orignal version written by Kevin Boone, August 98 Modified for JDK1.2 July 1999 ==================================================================*/
import java.awt.*; import java.applet.Applet; import java.awt.event.*; import java.util.Calendar; public class ClockApplet extends Applet implements Runnable { /* Use a big font for the numeral display. the Font constructor takes three arguments: 1. The typeface name (e.g., `roman', `helvetica') 2. The `style' of the font (e.g., bold, italic, normal) 3. The point size. Normal book text is usually 10-12 points in size (technically there are 72 points to the British inch */ Font numeralFont = new Font ("roman", Font.BOLD, 14); /* The attributes lastMinutes, lastSeconds, lastHours store the minutes, seconds and hours at the time the display was last re-drawn. We need this information so that the hands can be erased before they are redraw. This is to give the impression of movement. Note that I am using the value of `-1' for lastMinutes to indicate that there was not previous time. This will be the case when the program starts. We need to ensure that we do not attempt to erase the hand display when there is nothing to erase. As soon as the display has been drawn once, lastMinutes, lastSeconds and lastHours will be set to real values. */ int lastMinutes = -1, lastSeconds, lastHours; /* The following constants are used as arguments to the operation `drawHand'. They control how the hand should be drawn. */ final int ERASE = 0, DRAW = 1; final int LINEHAND = 0, SHAPEHAND = 1; /* Following attributes describe the sizes of teh various parts of the display. In theory, all these can be determined from the fundamental one `overallRadius'. This itself is determined from the size of the applet itself. However, if we have to calculate all of these values every time a hand is redraw, it will slow the program down and lead to increasd flicker. So we save all these things as attributes. These attributes are all calculated by the operation calculateAndSetBasicSizeAttribtues(). All the values are in pixels. */ // The overall radius of the clock face (right up // the very edge. If the applet is tall and thin, // the overall radius will be based on the width. // If it is short and wide, it is based on the // height. This is because the clock display must // be a circle, whatever the shape of the applet's // screen area int overallRadius; // Width of the applet int width; // Height of the applet int height; // X and Y co-ordinates of the centre of the applet. // This is where all the clock hands start from int centreX; int centreY; /* effectiveFaceRadius is the radius of the circle which joins the centres of the clock figures. If the clock figures are drawn on a circle the same size as the overall radius, then some of the figures will be off the edge of the display. This attribute is calculated by examining the height and width of the text of the largest number (`12') that appears on the clock face. */ int effectiveFaceRadius; // The height of the clock figures, in pixels int maxTextWidth; // The width of the largest clock figure (`12'), in pixels int maxTextHeight; // The distance from the top-left corner to the bottom-right // corner of the figure `12'. This is used to calculate how // long the clock second hand should be int radiusLostByText; // Keep going is set to `true' initially, and the applet will // continue to update the display until it is set to false. // The value is set to false when the Browser calls the applet's // `stop' operation (to indicate that the applet should stop // running. boolean keepGoing = true; /*================================================================== ClockApplet constructor Doesn't do much in this program; just sets the background colour ==================================================================*/ public ClockApplet () { /// QUESTION: if I wanted to change the clock to have a /// red background, rather than a white one, changing /// the line below would not be enough. What other lines in /// the program should we change? How could it be made easier /// to change the background colour? setBackground(Color.white); } /*================================================================== drawHand Draws a clock hand in the specified position. The `position' argument takes a value from 0 (straight up) to 0.5 (straight down) and back to 1.0 (back to straight up. I.e., a complete circle is a variation from 0 to 1. This is to allow hour, minute and second hands to be drawn with the same operation, even though they take different values (e.g. hours are from 1 to 12, minutes are from 0 to 59). The constant `action' controls whether the hands are to be redrawn or erased. If action is `DRAW', then the hand is drawn in blue or black. If it is `ERASE' it is drawn in white. `Shape' controls whether to draw a second hand shape, or an hour/minute hand shape From a Java perspective, the trignometry of calculating the coordinates of the hands is not important; however, note that general maths functions like sine and cosine are in fact static member functions of the `Math' class. You should be aware that any moderately sophisticated graphical program is likely to involve a bit of mathematics. However, as this is not a maths course I don't propose to describe the calculations themselves. ==================================================================*/ protected void drawHand (double position, int radius, int action, int shape) { /// QUESTION: what does getGraphics() do? Why do we need it /// here? Graphics g = this.getGraphics(); // It is possible that this operation may be called while // the browser is removing the applet from the display. If // this happens, `getGraphics()' will return `null'. In // this case, don't attempt to redraw the screen, as the // program will crash if (g == null) return; // In most `real' clocks, the hands do not originate // exactly from the centre, but a little way beyond // the centre. I am going to call this distance the // `overshoot radius' (lacking a better term). In this // program I have set the overshoot radius 10 // percent on the size of the hand itself. This figure // is also used to control the `thickness' of the hour // and minute hands int overshootRadius = overallRadius / 10; // As the `position' argument lies between 0 and 1, we // must convert this into a `real' anglue in radians. // Note that the constact `pi' is Math.PI in Java double angle = position * 2 * Math.PI; /* We will be drawing the shapes of the hour hand and the minute hand using `drawPolygon' (to draw the outline) and `fillPolygon' to draw the inside. These operations (which are in the Graphics class) take as input two arrays of integers. These arrays are the X and Y co-ordinates of the points that make up the shape to draw. So we calculate both these arrays, and pass them to the appropriate operations. Again, as this is not a maths course I don't propose to explain how the co-ordinates are calculated. */ int x[] = { centreX - (int)(overshootRadius * Math.sin(angle)), centreX - (int)(overshootRadius / 2.0 * Math.sin(angle+Math.PI/2)), centreX + (int)(radius * Math.sin(angle)), centreX - (int)(overshootRadius / 2.0 * Math.sin(angle-Math.PI/2)), }; int y[] = { centreY + (int)(overshootRadius * Math.cos(angle)), centreY + (int)(overshootRadius / 2.0 * Math.cos(angle+Math.PI/2)), centreY - (int)(radius * Math.cos(angle)), centreY + (int)(overshootRadius / 2.0 * Math.cos(angle-Math.PI/2)), }; // Depending on whether `action' is `DRAW' or `ERASE', // draw the hands in colour or in white if (action == DRAW) { if (shape == SHAPEHAND) { /// QUESTION: what does `Colour(0, 100, 200)' mean? g.setColor (new Color(0, 100, 200)); g.fillPolygon (x, y, 4); g.setColor (Color.black); g.drawPolygon (x, y, 4); } else { g.setColor (Color.black); g.drawLine (x[0],y[0],x[2],y[2]); } } else { // Erase if (shape == SHAPEHAND) { g.setColor (Color.white); g.fillPolygon (x, y, 4); g.drawPolygon (x, y, 4); } else { g.setColor (Color.white); g.drawLine (x[0],y[0],x[2],y[2]); } } } /*================================================================== drawClockFace Draw the clock face, i.e., the set of figures round the edge of the display. We use the attribute `effectiveFaceRadius' to determine the size of the circle that the figures lie on ==================================================================*/ protected void drawClockFace(Graphics g) { g.setFont (numeralFont); for (int i = 0; i < 12; i ++) { double angle = (i + 1) / 12.0 * 2.0 * Math.PI; g.drawString (Integer.toString(i+1), centreX + (int)(effectiveFaceRadius * Math.sin(angle) - maxTextWidth / 4), centreY - (int)(effectiveFaceRadius * Math.cos(angle) - maxTextHeight / 2 - 2)); } } /*================================================================== calculateHandRadius Work out the size of the display that is available for drawing the clock hands, taking into account the numerals around the edge. This is very simple: we just subtrace the distance across the largest figure (this is the attribute `radiusLostByText') from the overall radius of the clock ==================================================================*/ int calculateLargestHandRadius () { int radius = overallRadius - radiusLostByText; return radius; } /*================================================================== paint `paint' is called automatically by the Java system, when it knows the program's display has to be redrawn. This will happen when the applet is constructed, and whenever it is redraw after, for example, the browser's window is uncovered. In this case we just draw the clock face (that is, the figures). The hands are drawn every second by updateTime() ==================================================================*/ public void paint (Graphics g) { drawClockFace(g); } /*================================================================== updateTime Draw the clock hands, but not the face. The face only needs to be drawn when the applet needs to be redrawn. Java (via the Web browser) tells it when to do this. updateTime is called once a second by `run' This is the main animation procedure in the applet. It tries to make the display drawing as smooth as possible, by doing all the calculations before drawing anything. Actually, it is not perfect because some calculations are done during each call to drawHand() ==================================================================*/ void updateTime () { // Get the current time (hours, minutes and seconds) Calendar now = Calendar.getInstance(); int hours = now.get(Calendar.HOUR); int minutes = now.get(Calendar.MINUTE); int seconds = now.get(Calendar.SECOND); int handRadius = calculateLargestHandRadius(); // Erase the hands in their previous positions // If lastMintes is -1, this indicates that there were // no previous positions, so there is not need to erase if (lastMinutes != -1) { drawHand (lastMinutes/60.0, (int)(0.85*handRadius), ERASE, SHAPEHAND); drawHand (lastHours/12.0 + lastMinutes/60.0/12.0, (int)(0.6 * handRadius), ERASE, SHAPEHAND); drawHand (lastSeconds/60.0, (int)(0.9 * handRadius), ERASE, LINEHAND); } // Now draw the hands in their new positions drawHand (minutes/60.0, (int)(0.85 * handRadius), DRAW, SHAPEHAND); drawHand (hours/12.0 + minutes/60.0/12.0, (int)(0.6 * handRadius), DRAW, SHAPEHAND); drawHand (seconds/60.0, (int)(0.9 * handRadius), DRAW, LINEHAND); /// QUESTION: what do these three lines do, and why? lastHours = hours; lastMinutes = minutes; lastSeconds = seconds; } /*================================================================== calculateAndSetBasicSizeAttributes This operation is called by `start' to set up the attributes that contain important size information. This could be done every time a hand is re-drawn, but this would be very slow. As applets don't normally change size, we only call this operation once when the program starts. However, if we wanted to convert this applet into an application, where the user could change the size of the window, we would need to calculate new sizes whenever the window size changed. So I have grouped these calculations into one operation to make this easier to implement if necessary ==================================================================*/ void calculateAndSetBasicSizeAttributes() { width = getSize().width; height = getSize().height; centreX = width/2; centreY = height/2; overallRadius = Math.min(width, height) / 2; Graphics g = getGraphics(); g.setFont (numeralFont); /* FontMetrics is a very important class in programs that display text. Its operations can be used to determine the sizes of characters and lines as they appear on the display (in pixels). */ FontMetrics fm = g.getFontMetrics(); maxTextWidth = fm.charsWidth ("12".toCharArray(), 0, 2); /// QUESTION: what is an `ascent' and a `descent'? maxTextHeight = fm.getMaxAscent() - fm.getMaxDescent(); radiusLostByText = (int)Math.sqrt(maxTextHeight * maxTextHeight + maxTextWidth * maxTextWidth); effectiveFaceRadius = overallRadius - radiusLostByText / 2 - 4; } /*================================================================== start Get things moving by creating a new thread for this program and running it by calling `start' Multi-threading will be covered later in the course; don't worry if this operation doesn't make sense at the moment ==================================================================*/ public void start () { calculateAndSetBasicSizeAttributes(); Thread thisThread = new Thread(this); // Calling start (Thread.start()) starts the // new thread, and causes `run' (runnable.run() // _and_ Thread.run()) to be executed. This starts the // process of drawing the clock hands thisThread.start(); } /*================================================================== stop The browser (or applet viewer) has decided that the user wants the applet to stop running. ==================================================================*/ /// QUESTION: in the program `Calculator.java' we did not need a /// `stop' operation. What is different about this program that means /// we have to process `stop'? public void stop () { keepGoing = false; } /*================================================================== run The `run' operation controls the work of the applet. It is started by `thisThread.start' in operation `start', and runs until the applet is terminated by the browser ==================================================================*/ public void run () { // Redraw once per second, as long as `keepGoing' is true. // This will be the case until `stop' is called, which // sets keepGoing to false // It simply calls `updateTime' once every second while (keepGoing) { // The operation `Thread.sleep()' causes the // the program to stop for a certain length of // time. The time is specified in // milliseconds, so a one-second wait is 1000 // milliseconds. try {Thread.currentThread().sleep(1000);} catch (InterruptedException e){} updateTime (); } } }