2.3 The Java API Documentation

• What follows are the contents of the Java Application Programming Interface (API) Documentation for the system supplied class Point.

• The complete online Java API documentation can easily be found through a Web search.

• This is a comprehensive reference for questions about programming in Java.

• An explanation of the excerpt from the documentation is given following it.

• java.awt Class Point

• java.lang.Object | +--java.awt.geom.Point2D | +--java.awt.Point All Implemented Interfaces:

• Cloneable, Serializable

• public class Point • extends Point2D • implements Serializable• A point representing a location in (x, y) coordinate

space, specified in integer precision. • Since: • JDK1.0 • See Also: • Serialized Form

Inner classes inherited from class java.awt.geom.Point2DPoint2D.Double, Point2D.Float

Inner classes inherited from class java.awt.geom.Point2DPoint2D.Double, Point2D.Float

Field Summary int x

The x coordinate. int y

The y coordinate.

 

Constructor SummaryPoint() Constructs and initializes a point at the origin (0, 0) of the coordinate space.

Point(int x, int y) Constructs and initializes a point at the specified (x, y) location in the coordinate space.

Point(Point p) Constructs and initializes a point with the same location as the specified Point object.

Method Summary boolean

equals(Object obj) Determines whether an instance of Point2D is equal to this point.

Point

getLocation() Returns the location of this point.

double

getX() Returns the X coordinate of the point in double precision.

double

getY() Returns the Y coordinate of the point in double precision.

void

move(int x, int y) Moves this point to the specificed location in the (x, y) coordinate plane.

void setLocation(double x, double y) Sets the location of this point to the specified float coordinates.

void setLocation(int x, int y) Changes the point to have the specificed location.

void setLocation(Point p) Sets the location of the point to the specificed location.

String toString() Returns a string representation of this point and its location in the (x, y) coordinate space.

void translate(int x, int y) Translates this point, at location (x, y), by dx along the x axis and dy along the y axis so that it now represents the point (x + dx, y + dy).

• The information given at the top of the documentation concerns the naming of the class and where it is located.

• System supplied classes are arranged in packages. • If you scan through the information at the top you will

eventually find this: • java.awt.Point. • “awt” stands for “abstract windowing toolkit”. • This is the name of a package in Java which includes

classes related to doing graphical things.

• Point is one of those classes. If a program uses a system supplied class, a line like this is put at the top of the code:

• • import java.awt.Point;• • The idea is that this will make the class available for use in the

program. • This will be done in the example programs. • It is possible to import all classes in a package at once. • If you chose to do this, you would use the * as a wildcard:• • import java.awt.*;

• The next segment of interest in the documentation is entitled “Field Summary”.

• In the documentation, what are referred to in these notes as instance variables are referred to as fields.

• In other words, you discover from this documentation that an object created from the Point class will have two instance variables, an x coordinate and a y coordinate.

• These instance variables are given the type “int”, which signifies that these coordinates can take on integer values.

• The next segment in the documentation is entitled “Constructor Summary”.

• Constructors are special pieces of code used for creating instances of classes.

• Constructors have a form reminiscent of methods—they have a name followed by a set of parentheses which may or may not contain parameters.

• Constructors are not methods. • Their name is the same as the class they belong to. • As you can see, a single class may have more than one

constructor. • The system can tell them apart because they have

different parameter lists. • In the documentation the types of the parameters are

shown. • For the time being we will restrict our attention to

examples with parameters of the type “int”.

• The last segment of the documentation is the “Method Summary”.

• This gives all of the methods by name and all of their parameters by name, including their types.

• There can be different methods with the same name.

• The system tells them apart by their parameter lists. • It is only through these methods that a program can

affect the instance variables, the x and y coordinates, of a Point object that has been created.

• As you can see, int and double are two different numeric types.

• The meaning of types will be covered in the next unit.

• For the time being, examples will be restricted to the int, or integer type.

• This type can hold whole number values.