YOPS -- Example 3: Building a Line Tool

3. Building a Line Tool

For this example, we will construct a tool in YOPS which allows us to create lines by "rubber-banding" them on the display. A user will press the mouse to specify the starting point of a line, and then drag around to see the line they are creating, and release to add the line to the display.

We will call this tool the Line Tool. Here is our starting shell class for the Line Tool which creates a YOPS window and adds the LineTool to the YOPS interface:

import java.awt.Color;
import yops.*;

public class LineTool {
   public String toString() {
      return "Line Tool";
   }
   public static void main(String args[]) {
      YOPS yops = new YOPS(200, 300, 2);
      yops.setTool(new LineTool());
   }
}

When run, this class will create a YOPS window with a Line Tool that currently does nothing. We want the Line Tool to create a Line graphics object when the mouse is pressed and add it to a GraphicsPanel so that the line is visible. Further, when the mouse is dragged, we want the ending points of that line to change so we have our rubber banding effect.

Since we want our tool to react to the user's mouse events, we can include one or more of the following methods in our tool, depending on the kind of mouse event we're interested in. In each case, the parameters are the GraphicsPanel in which the mouse event occurred, along with the x and y pixel coordinates of mouse cursor location.

mousePressed(GraphicsPanel panel, int x, int y) - This method will be called on the tool when the user presses the left mouse button within the panel.
mouseReleased(GraphicsPanel panel, int x, int y) - This method will be called on the tool when the user releases the left mouse button. Note that if the user was holding down the mouse button and moved off the panel, then the reported (x,y) coordinate may be outside the boundary of the panel.
mouseMoved(GraphicsPanel panel, int x, int y) - this method will be called on the tool when the user moves the mouse to the (x,y) location within the panel
mouseDragged(GraphicsPanel panel, int x, int y) - this method will be called on the tool when the user moves the mouse to the (x,y) location within the panel while holding down the left mouse button.

For our purposes, we are interested in the mousePressed and mouseDragged methods. Our mousePressed will construct a new Line object whose endpoints are the x and y coordinates the mouse was pressed at. As the mouseDragged is to change the end point to the line to create our "rubber banding" effect, it must have a reference to the Line object creatd in the mousePressed method and the x and y coordinates of the starting point. Thus we will need instance variables to store these values between the mousePressed and mouseDragged methods as follows:

public class LineTool {
   int x1, y1;
   Line line;

   public void mousePressed(GraphicsPanel p, int x, int y) {
      x1 = x;
      y1 = y;
      line = new Line(x1, y1, x1, y1);
      p.add(line);   // Displays the line on the GraphicsPanel
   }

   public void mouseDragged(GraphicsPanel p, int x2, int y2) {
      line.setCorners(x1, y1, x2, y2);
   }

   // toString from above
   // main from above
}

The is a full implementation for the Line Tool, but let's add another extension that allows us to modify the color of a line being created. To do so, we will need an integer instance variable to store the blue intensity value and a mechanism to let the user modify this blue value.

YOPS provides a simple way for users to input such primitive values. For this purpose, a tool can have one or more methods whose method name begins with the word "set" and that has an int, double, or boolean parameter and a void return type.

For each numeric set method (int or double), YOPS will show a labeled slider. The "set" method will be called whenever the user adjusts the slider. Parameter values will be reported to the method as a percent (0 to 100), which can be adjusted as needed when the "set" method is called. For example, if we want values in the range 0 to 255, we can multiply the supplied slider value by 2.55 to get the desired result.

For each boolean set method (int or double), YOPS will show a labeled checkbox. The "set" method will be called whenever the user checks or unchecks the box.

Since our Line Tool will allow the user to adjust the blue of the Line being created, we will write a set method for an integer value and scale the value to be from 0 to 255. We will store this value in an instance variable, and then use the value when a Line is constructed to set its foreground color to a new Color object which has the blue intensity value stored in our instance variable. To accomplish this, we add the following code:

public class LineTool {
   // Instance variables from above
   int blue;

   public void mousePressed(GraphicsPanel p, int x, int y) {
      x1 = x;
      y1 = y;
      line = new Line(x1, y1, x1, y1);
      p.add(line);   // Displays the line on the GraphicsPanel

      line.setForeground(new Color(0, 0, blue));
   }

   public void setBlue(int amount) {
      blue = (int) (amount * 2.55);
   }

   // mouseDragged from above
   // toString from above
   // main from above
}

The YOPS window will now have a slider for the value of the blue instance variable. Adjusting the slider will modify the intensity of the blue in a line to be created.

Download our example LineTool.java

Continue to 4. Other Features >

YOPS: Ye Olde Photo Shoppe

3. Building a Line Tool