The javabook Package

Transcription

1 A The javabook Package We document the javabook classes in this appendix. You can get information on the standard Java packages from a number of sources. If you use commercial Java compilers from Borland, Microsoft, Symantec, and others, you can access desired information from their help menu. You can also access the online documentation from the Web site at packages.html. Reference books on the standard Java packages such as P. Chan and R. Lee, The Java Class Libraries, Vol. 1 and 2, 2nd ed. [Reading, MA: Addison-Wesley, 1998] and D. Flanagan, Java in a Nutshell, 2nd ed. [Sebastapol, CA: O Reilly & Associates, Inc., 1997] are good sources of information. If you are interested in the official language specification of Java, you should get a copy of J. Gosling, B. Joy, and G. Steele, The Java Language Specification, [Reading, MA: Addison-Wesley, 1996]. Documentation provided in this appendix is intended for the users of the package. As such, only the public methods and constants are included (in case of JavaBookDialog, the protected method is included also). We direct those who are interested in learning how the classes are implemented to our Web site at The Web site includes the most up-to-date online documentation on the javabook package that you can download. We plan to update the javabook package periodically, so please visit our Web site regularly. Also, if you notice any discrepancy between the information provided in this 823

2 824 Appendix A The javabook Package appendix and the software, please visit our Web site to get the most up-to-date information. PACKAGE: Class Convert DrawingBoard Format InputBox JavaBookDialog ListBox MainWindow MessageBox MultiInputBox OutputBox ResponseBox SketchPad javabook Description The class provides methods for converting a value of one data type to another data type. A frame window that is capable of drawing lines, circles, and rectangles. The class provides methods for formatting integers, real numbers, and strings. A dialog for getting an input value from the user. An InputBox object can be used to accept integers, real numbers, and strings. An abstract superclass that encapsulates behavior common to all dialogs in this package: InputBox, ListBox, MessageBox, MultiInput- Box, OutputBox, and ResponseBox. A dialog for displaying a list of choices and allowing the user to select a choice in the list. A frame window that serves as the main window of an application. A MainWindow object is almost as big as the screen and is displayed at the center of the screen. A dialog for displaying a single line of text. A MessageBox object is intended for displaying a short warning or error message. A dialog for getting multiple input values from the user. A MultiInputBox object can be used to accept N string values. A dialog for displaying multiple lines of text. A dialog for getting a yes or no answer from the user. A frame window that allows the user to draw freeform lines using a mouse. For each class description, we include The purpose of the class. The page and section number where the class is introduced. The ancestors of the class. If the superclass is also in the javabook package, then only this superclass is shown. The public constants of the class. The public methods of the class.

3 825 javabook.convert This class provides methods for converting a data value of one data type to another data type. This class is noninstantiable; all methods are class methods. Introduced in: Section 9.4 page 454. java.lang.object Convert toboolean tochar todouble tofloat toint tolong tostring public static boolean toboolean ( String str ) Converts the argument str to a boolean. public static char tochar ( String str ) Converts the argument str to a char. public static double todouble ( String str ) Converts the argument str to a double. public static float tofloat ( String str ) Converts the argument str to a float. public static int toint ( String str ) Converts the argument str to an int.

4 826 Appendix A The javabook Package public static long tolong ( String str ) Converts the argument str to a long. public static String tostring ( boolean bool ) public static String tostring ( char ch ) public static String tostring ( double number ) public static String tostring ( float number ) public static String tostring ( int number ) public static String tostring ( long number ) Converts the argument to a String. javabook.drawingboard This class is used in the sample program from Chapter 6. A DrawingBoard object supports methods for drawing circles, lines, and rectangles. Introduced in: Section 6.6 page 267. MainWindow DrawingBoard DrawingBoard drawcircle drawline drawrectangle setcolor show public DrawingBoard ( ) public DrawingBoard ( String title )

5 827 A DrawingBoard object with the default title DRAWING BOARD is created. The window is not resizable and the background color is set to white. public void drawcircle ( int x, int y, int r ) Draws a circle with radius r and whose center point is (x, y). public void drawline ( int x1, int y1, int x2, int y2 ) Draws a line from point (x1, y1) to (x2, y2). public void drawrectangle ( int x, int y, int w, int h ) public void drawrectangle ( Rectangle rect ) The first version draws a rectangle with width w and height h and its top-left corner at position (x, y). The second version draws a rectangle with the dimension set by the Rectangle object rect. public void show ( ) Overrides the superclass s show to initialize the data member Graphics object so the drawing works correctly. See also: java.awt.rectangle Explanation of the coordinate system for the drawing is given in Section 2.6 and Section javabook.format This class provides methods for formatting a value in a field of a given length. Three possible alignments are left, center, and right. The alignment is done by converting a value to a String with a given length and placing the value at the beginning, middle, or the end of the String. This class is noninstantiable; all methods are class methods. Introduced in: Section 7.7 page 325.

6 828 Appendix A The javabook Package java.lang.object Format centeralign leftalign rightalign public String centeralign ( int width, int decimalplaces, double num ) public String centeralign ( int width, long num ) public String centeralign ( int width, String str ) Returns a String that has width characters in it. The value num or str is positioned at the center of the resulting String. For the first version, the resulting String will have a decimal point and the designated number of decimal places. If the given value cannot fit into the width characters, the value converted to a String without any alignment is returned. public String leftalign ( int width, int decimalplaces, double num ) public String leftalign ( int width, long num ) public String leftalign ( int width, String str ) The same functionality as centeralign, but with the left alignment. public String rightalign ( int width, int decimalplaces, double num ) public String rightalign ( int width, long num ) public String rightalign ( int width, String str ) The same functionality as centeralign, but with the right alignment.

7 829 javabook.inputbox A dialog that allows the user to enter a value. An InputBox object can accept both numerical and textual values. The user cannot close the dialog until he/ she enters a valid value of the designated data type. Introduced in: Section 3.5 page 103. JavaBookDialog InputBox InputBox getinteger getfloat getstring public InputBox ( Frame owner ) public InputBox ( Frame owner, String title) Creates an InputBox object with owner as its controlling Frame object. In the second version, the title of a dialog is set to the String passed as the second argument. public int getinteger ( ) public int getinteger ( String prompt ) The method returns the integer value entered by the user. This method does not complete until the user enters a valid integer. For the first version, the prompt is set to a default word Enter an integer:. In the second version, the prompt is set to the passed String argument. public float getfloat ( ) public float getfloat ( String prompt ) The same behavior as the getinteger methods. The getfloat methods return a float instead of an int.

8 830 Appendix A The javabook Package public String getstring ( ) public String getstring ( String prompt ) The same behavior as the getinteger methods. The getstring methods return a String instead of an int. javabook.javabookdialog An abstract class that encapsulates behavior common to the other dialogs in this package. Create a subclass of JavaBookDialog if you want your dialog to include the common behavior of placing the dialog at the center of the screen. A subclass of JavaBookDialog must implement the abstract method adjustsize. Introduced in: Section page 765 java.lang.object java.awt.component java.awt.container java.awt.window java.awt.dialog JavaBookDialog show public void show ( ) Overrides the superclass s show. This method calls the protected adjustsize method before making the dialog visible. If you create a subclass of JavaBookDialog, then you must define the adjustsize method in your subclass.

9 831 Protected Methods: adjustsize abstract protected void adjustsize ( ) Define this method in your subclass. You use this method to adjust the size of a dialog based on the components placed on the dialog. See also: For a sample of defining a subclass of JavaBookDialog, please read the StudentNameDialog class in Section javabook.listbox A dialog that allows the user to select an entry from a list of selections. Introduced in: Section 6.4 page 256. JavaBookDialog ListBox CANCEL NO_SELECTION ListBox additem deleteitem getselectedindex getselecteditem iscanceled public ListBox ( Frame owner ) public ListBox ( Frame owner, String title ) public ListBox ( Frame owner, boolean modal ) public ListBox ( Frame owner, String title, boolean modal )

10 832 Appendix A The javabook Package Creates a ListBox object with owner as its controlling Frame object. The default title of the dialog is Select One: and the default mode is modal. Pass a String value and/or a boolean value to change the default. You pass true for modal and false for modeless dialogs. public void deleteitem ( int index ) Deletes the entry at position index. The topmost entry is index 0, the next is index 1, and so forth. public void additem ( String entry ) Adds an entry to the list. The newly added entry is placed at the bottom of the list, that is, the newly added entry has the highest index value. public int getselectedindex ( ) Returns the index of the entry selected by the user. If the user clicks the CANCEL button or closes the dialog, then the public constant CANCEL is returned. If the user clicks the OK button without selecting an entry, then the public constant NO_SELECTION is returned. public String getitemfromindex( int index ) Returns the value (String) of the entry at position index. public boolean iscanceled ( ) Returns true if the dialog was canceled or closed without an entry being selected. Returns false otherwise. javabook.mainwindow A frame that serves as the main window of an application. By default, the frame size is almost as large as the screen, and it is displayed at the center of the screen. Introduced in: Section 2.1 page 42.

11 833 java.lang.object java.awt.component java.awt.container java.awt.window java.awt.frame MainWindow MainWindow show public MainWindow ( ) public MainWindow ( String title ) Creates a MainWindow object with the text Sample Java Appliation as its default title. Use the second constructor to change the default title. public void show ( ) Displays the MainWindow object. javabook.messagebox A dialog that displays a single line of text. This dialog is suitable for displaying error or warning messages. Introduced in: Section 2.5 page 65.

12 834 Appendix A The javabook Package JavaBookDialog MessageBox MessageBox show public MessageBox ( Frame owner ) public MessageBox ( Frame owner, boolean modal ) Creates a MessageBox object with owner as its controlling Frame object. The default mode is modal. The second argument determines the modality: pass true for modal and false for modeless. public void show ( long number ) public void show ( double number ) public void show ( String str ) public void show ( StringBuffer strbuf ) Displays the passed argument. Non-String values are converted to a String value before the display. The dialog appears at the center of the screen. public void show ( long number, int x, int y ) public void show ( double number, int x, int y ) public void show ( String str, int x, int y ) public void show ( StringBuffer strbuf, int x, int y ) Displays the passed argument. Non-String values are converted to a String value before the display. The top left corner of the dialog is set to position (x, y). javabook.multiinputbox A dialog that allows the user to enter N input String values. TextField objects are used for accepting input values. Introduced in: Section 9.4 page 452.

13 835 JavaBookDialog MultiInputBox MultiInputBox getinputs iscanceled setlabels setvalue public MultiInputBox ( Frame owner, int size ) public MultiInputBox ( Frame owner, String[] labels ) Creates a MultiInputBox object with owner as its controlling Frame object. The second argument can be either an integer or an array of String objects. The integer value determines N the number of input values the user can enter. If an array of String values is passed, then the value for N is determined by the length of the array. In addition, the String values will become the labels for the N TextField objects. public String[] getinputs ( ) Returns the N input text values entered by the user. An empty String is returned for a TextField that has no entry. public boolean iscanceled ( ) Returns true if the dialog was canceled or closed. Returns false otherwise. public void setlabels ( String[] labels ) Sets the labels for N TextField objects. public void setvalue ( int index, String value ) The text of the TextField object at position index is set to value. The N TextField objects are indexed by using zero-based indexing, that is, the topmost object has index 0. This method is useful for showing the user a typically expected input value. See also: java.awt.textfield

14 836 Appendix A The javabook Package javabook.outputbox A dialog for displaying multiple lines of text. This dialog is intended for displaying program output. Introduced in: Section 3.6 page 106. JavaBookDialog OutputBox OutputBox appendtofile print printline savetofile setfont skipline waituntilclose public OutputBox ( Frame owner ) public OutputBox ( Frame owner, String title ) public OutputBox ( Frame owner, int width, int height ) public OutputBox ( Frame owner, int width, int height, String title ) Creates an OutputBox object with owner as its controlling Frame object. public void appendtofile ( String filename ) Appends the contents of an OutputBox to the file whose name is filename. If no such file exists, then the method creates a new file and saves the contents of an OutputBox.

15 837 public void print ( boolean bool ) public void print ( char ch ) public void print ( double num ) public void print ( long num ) public void print ( String str ) public void print ( StringBuffer strbuf ) Prints out the argument. public void printline ( boolean bool ) public void printline ( char ch ) public void printline ( double num ) public void printline ( long num ) public void printline ( String str ) public void printline ( StringBuffer strbuf ) Prints out the argument and moves the cursor to the next line. public void savetofile ( String filename ) Saves the contents of an OutputBox to the file whose name is filename. If the file already exists, then the original contents of the file will be replaced by the contents of an OutputBox. public void setfont ( Font newfont ) Sets the font to newfont. The default is size 12, plain Courier font. public void skipline ( int numlines ) Skip numlines lines. The effect is the same as if you press the ENTER key numlines times. public void waituntilclose ( ) An OutputBox dialog is always modeless. There are times, however, you want to close the dialog before continuting the execution of a program, that is, you want it to behave like a modal dialog. When this method is called, the program execution will not continue until the user closes the OutputBox object. See also: java.awt.font

16 838 Appendix A The javabook Package javabook.responsebox A dialog for displaying multiple lines of text. This dialog is intended for displaying program output. Introduced in: Section 7.4 page 312. JavaBookDialog ResponseBox YES NO CANCEL BUTTON1 ( == YES) BUTTON2 ( == NO ) BUTTON3 ResponseBox prompt setlabel public ResponseBox ( Frame owner ) public ResponseBox ( Frame owner, int buttoncount ) Creates a ResponseBox object with owner as its controlling Frame object. The default ResponseBox object has two buttons labeled Yes and No. These buttons are identified by the class constants YES and NO. You can create a ResponseBox object with N, 1 ð N ð 3, buttons by passing N as the second argument. The buttons are identified from left to right by the class constants BUTTON1, BUTTON2, and BUTTON3. public int prompt ( String str) Prompts the user for a response. The argument str is the query you pose to the user. The user responds to the query by clicking one of the buttons. public void setlabel ( int id, String label) Set the label of button id to label.

17 839 javabook.sketchpad A frame window that allows the user to draw freeform lines using a mouse. You draw lines by dragging the mouse and erase them by clicking the right mouse button (Command-click on the Mac). Introduced in: Section 1.6 page 33. MainWindow SketchPad SketchPad public SketchPad ( ) Creates a SketchPad object.

18 840 Appendix A The javabook Package