Richard G Baldwin (512) 223-4758, baldwin@austin.cc.tx.us, http://www2.austin.cc.tx.us/baldwin/

The AWT Package, The Dialog Class

Java Programming, Lesson # 138, Revised 01/16/98.

Preface

Students in Prof. Baldwin's Advanced Java Programming classes at ACC are responsible for knowing and understanding all of the material in this lesson.

Introduction

This series of lessons is concentrating on package java.awt where most of the functionality exists for providing the user interface to your application or applet.

We are looking at the variety of components that are available to combine with layout and event handling to produce an effective GUI.

Dialog

This lesson will deal with the Dialog class. The official description taken from the JDK 1.1 documentation is:
 
"A class that produces a dialog - a window that takes input from the user. The default layout for a dialog is BorderLayout. 

Dialogs are capable of generating the following window events: WindowOpened, WindowClosing, WindowClosed, WindowActivated, WindowDeactivated."

It is often useful in the understanding of a class to picture the position of that class in the inheritance hierarchy. The Dialog class extends Window which extends Container which extends Component.

As of 3/14/97, the Dialog class has no fields and has the following public constructors:
 
  • Dialog(Frame) -- Constructs an initially invisible Dialog with an empty title. 
  • Dialog(Frame, boolean) -- Constructs an initially invisible Dialog with an empty title. 
  • Dialog(Frame, String) -- Constructs an initially invisible Dialog with a title. 
  • Dialog(Frame, String, boolean) -- Constructs an initially invisible Dialog with a title. 
All four versions of the constructor require a parameter of type Frame. According to the JDK 1.1 documentation, this is the parent or owner of the Dialog object.

The boolean parameter in two versions of the constructor determines whether or not the Dialog object is modal. According to the JDK 1.1 documentation:
 
"A modal Dialog grabs all the input from the user."
Stated differently, for these two versions of the constructor, if the boolean parameter is true, then the Dialog object blocks input to other windows when the Dialog object is visible on the screen.

Note that the Dialog object can also be made modal after it is instantiated using the setModal() method.

As of 3/14/97, the Dialog class has nine methods, and inherits many more methods from its superclasses. An interesting subset of the methods in the Dialog class is shown below:
 
  • show() -- Shows the dialog. 
  • getTitle() -- Gets the title of the Dialog. 
  • setTitle(String) -- Sets the title of the Dialog. 
  • isModal() -- Returns true if the Dialog is modal. 
  • setModal(boolean) -- Specifies whether this Dialog is modal. 
  • isResizable() -- Returns true if the user can resize the dialog. 
  • setResizable(boolean) -- Sets the resizable flag. 
The official description of the show() method taken directly from the JDK 1.1 documentation is:
 
"Shows the dialog. This will bring the dialog to the front if the dialog is already visible. If the dialog is modal, this call will block until the dialog is taken down by calling hide or dispose. 

It is permissible to show modal dialogs from the event dispatching thread because the toolkit will ensure that another dispatching thread will run while the one which invoked show is blocked."

Let's start our investigation of the Dialog class by taking a look at a program containing the minimum code necessary to get a Dialog object to appear on the screen. This program will also illustrate some interesting aspects of a Dialog object.

Minimal Sample Program

This program is designed to be compiled and run under JDK 1.1

The purpose of this program is to illustrate the minimum code necessary to get a Dialog object to appear on the screen. The following description is based on executing this program under JDK 1.1.3 and Win95.

When the program starts, a Frame object and a Dialog object should both appear on the screen. The Dialog object should be about half the size of the Frame object in both dimensions.

The Dialog object should contain a title and a close box. However, the close box is not operative.

The Dialog object can be moved and it can be resized. It does not have a minimize button or a maximize button, but the control box in the upper left-hand corner can be used to minimize and maximize the object. The Dialog object can be placed anywhere on the screen. Its position is not restricted to the interior of its parent, the Frame object.

On a Win95 system, the Frame object has a white background and the Dialog object has a grey background. (This may depend on some of the setup parameters in Win95.) When the title bar is selected on either object, the title bar has a blue background and white letters.

The Frame object appears to have a border while the Dialog object does not appear to have a border. It differs in appearance from the Frame object.

The program was tested using JDK 1.1.3 running under Win95.

Note that the Dialog, when created using JDK 1.1.3 under Win 95, has both a close box in the upper right-hand corner and a control box in the upper left-hand corner. Although it doesn't have minimize and maximize buttons, those capabilities exist, and are active in the control box. It is the opinion of this author that it would be better if it were possible to create a Dialog without these controls showing.

Interesting Code Fragments from Minimal Sample Program

The interesting code in this program is the following three statements. The first statement instantiates the Dialog object as a child of the main object, this. The second statement establishes the initial size of the Dialog object. The third statement makes the Dialog object appear on the screen.
 
    Dialog myDialog = new Dialog(this,"Dialog");

    myDialog.setSize(125,75);

    myDialog.show();//make the Dialog object appear
A listing of the complete program is contained in the next section. Before going further, it might be a good idea to confirm that you can duplicate these results on your platform.

Program Listing for Minimal Sample Program

A complete listing of the program follows. See the previous sections for an operational description of the program.
 
/*File Dialog01.java Copyright 1997, R.G.Baldwin

This program is designed to be compiled and run under 

JDK 1.1



The purpose of this program is to illustrate the minimum

code requirement to get a Dialog object to appear on the

screen



The program was tested using JDK 1.1.3 running under Win95.

**********************************************************/



import java.awt.*;

import java.awt.event.*;

//=======================================================//



public class Dialog01 extends Frame{

  public static void main(String[] args){

    new Dialog01();//instantiate an object of this type

  }//end main



  public Dialog01(){//constructor

    setTitle("Copyright 1997, R.G.Baldwin");  

    setSize(250,150);

    setVisible(true);

 

    Dialog myDialog = new Dialog(this,"Dialog");

    myDialog.setSize(125,75);

    myDialog.show();//make the Dialog object appear

  }//end constructor

  

}//end class Dialog01

//=======================================================//
That should explain the minimum that we need to know in order to create a Dialog object and cause it to appear on the screen. The next sample program will have more substance.

Operational Sample Program

This program is designed to be compiled and run under JDK 1.1 It produces two fully-functional Dialog objects, one Modal and the other nonModal.

A Frame object which will serve as the parent of two Dialog objects is instantiated. Since it will serve as a parent, it must be instantiated first.

A nonModal Dialog object is created containing a Button object. The Button object is used to close the Dialog object.

An ActionListener object is instantiated and registered on the Button object which belongs to the Dialog object.

This ActionListener object is instantiated from a shared ActionListener class. Code in the overridden actionPerformed() method of the ActionListener object closes the Dialog object by invoking setVisible(false). According to the previous description of the show() method, it would also have been possible to use hide() or dispose() to close the Dialog object.

A Modal Dialog object is created in the same manner. It also containing a Button object. As with the nonModal Dialog object, the Button object shares the same ActionListener class to invoke the setVisible(false) method to close the Modal Dialog object.

Two Button objects are created and placed on the Frame object. One is designed to show the nonModal Dialog object and the other is designed to show the Modal Dialog object.

These two Button objects share a common ActionListener class that is designed to show a Dialog object at a predefined size and a parameterized location. The location of the Dialog object is controlled by an integer offset parameter that is passed when the ActionListener object is instantiated.

To avoid overlap, the ActionListener objects for the two Button objects that show the Dialog objects in this program are instantiated with different offset values. Then when the Dialog objects are shown, they appear at different locations on the screen.

If you compile and run this program, it should begin with two Button objects visible. One of the Button objects can be used to show the nonModal Dialog object. The other can be used to show the Modal Dialog object. When the Modal Dialog object is not visible, you can show and close the nonModal Dialog object at will. You can also click the close box on the Frame object to terminate the program.

However, when the Modal Dialog is visible, you should not be able to perform any other operation within this program, but you should be able to start other programs. This mode of operation is sometimes referred to as "application modal".

When the Modal Dialog object is showing on a Win95 system and you attempt to perform some other operation within the program, you may receive an audible signal, possibly depending on how you have the sounds set up on your system.

A windowClosing() event listener object is instantiated and registered on the frame to terminate the program when the frame is closed. However, the frame cannot be closed while the Modal Dialog object is visible.

The program was tested using JDK 1.1.3 running under Win95.

Interesting Code Fragments from Operational Sample Program

The first interesting code fragment is the statement that instantiates the Frame object. We have seen many statements like this in earlier lessons. The thing that makes this one interesting is that because it will be used as the parent of two Dialog objects, it is necessary to instantiate the Frame object before instantiating the Dialog objects.
 
   Frame myFrame = new Frame("Copyright 1997, R.G.Baldwin");
The next interesting code fragment is typical of that used to
 
  • instantiate both of the Dialog objects, 
  • place a Button object in the Dialog object, 
  • instantiate and register an ActionListener object on the Button object. 
This is the fragment that creates the Modal Dialog object. The code used to create the nonModal Dialog object is essentially the same except that it does not have the true boolean parameter in the invocation of the constructor (shown highlighted in boldface below).
 
Dialog modalDialog = 

    new Dialog(myFrame,"Modal Dialog",true);

Button modalCloseButn = new Button("Close");

modalDialog.add(modalCloseButn);

modalCloseButn.addActionListener(

      new closeDialogListener(modalDialog));
This code fragment is followed by code to instantiate a couple of ordinary Button objects and register ActionListener objects on those buttons. We have seen code of this type many times in the past and won't discuss it further here.

The code to instantiate the Button objects is followed by code to finish constructing the Frame object. Again, this is old stuff for us by now.

The next interesting code fragment is the ActionListener class used to instantiate objects for showing a Dialog object.

Two aspects of this code are interesting. First, a parameterized constructor is used to save an offset value passed in as a parameter when the ActionListener object is instantiated. This offset value is combined with literal values in the code to control both the size and the location location of the Dialog object when it appears on the screen.

The second interesting aspect is that the show() method of the Dialog class is used to actually cause the Dialog object to appear on the screen.

Note also that the order of execution of the statements within the overridden actionPerformed() method is critical. If the show() method is executed before the setBounds() method on the Modal Dialog object, the setBounds() method used to control the location and size of the Dialog object has no effect. The size and location of the Modal Dialog object must be established before it becomes visible.
 
class showDialogListener implements ActionListener{

  Dialog aDialog;

  int Offset;

  

  //constructor

  showDialogListener(Dialog inDialog,int inOffset){

    aDialog = inDialog;

    Offset = inOffset;

  }//end constructor

  

  public void actionPerformed(ActionEvent e){

    //Following order is critical for a modal dialog.  

    aDialog.setBounds(Offset,Offset,150,100);

    aDialog.show();    

  }//end actionPerformed()

}//end class myModalActionListener
The next interesting code fragment is the overridden actionPerformed() method used to close the Dialog objects. The setVisible(false) method is used in this example. The earlier description of the show() method indicates that the hide() method or the dispose() method could also have been used for this purpose.
 
  public void actionPerformed(ActionEvent e){

    aDialog.setVisible(false);

  }//end actionPerformed()
A complete listing of the program follows in the next section.

Program Listing for Operational Sample Program

This section contains a complete listing of the program with additional comments. See the previous sections for an operational description of the program.
 
/*File Dialog02.java Copyright 1997, R.G.Baldwin

This program is designed to be compiled and run under 

JDK 1.1



A Frame object which will serve as the parent of two 

Dialog objects is instantiated.  Since it will serve as a 

parent, it must be instantiated first.



A nonModal Dialog object is created containing a Button 

object.  The Button object is used to close the Dialog 

object.  An ActionListener object is instantiated and 

registered on the Button object.  This object is 

instantiated from a shared ActionListener class.  Code in 

the overridden actionPerformed() method of the 

ActionListener object closes the Dialog object by invoking

setVisible(false).

 

A Modal Dialog object is created also containing a Button

object.  As with the nonModal Dialog object, the Button

object shares the same ActionListener class to invoke the

setVisible(false) method to close the Modal Dialog object.



Two Button objects are created and placed on the Frame 

object.  One is designed to show the nonModal Dialog 

object and the other is designed to show the Modal Dialog

object.  These two Button objects share a common 

ActionListener class that is designed to show a Dialog 

object at a predefined size.  The position of the dialog

object is controlled by an integer offset parameter that

is passed when the ActionListener object is instantiated.

To avoid overlap, the ActionListener objects for the two

Button objects that show the Dialog objects are 

instantiated with different offset values.  Then when the

Dialog objects are shown, they appear at different 

locations on the screen.



If you compile and run this program, it should begin with

two Button objects visible.  One of the Button objects can

be used to show the nonModal Dialog object.  The other can

be used to show the Modal Dialog object.  When the Modal 

Dialog is showing, you should not be able to perform any

other operation within this program, but you should be 

able to start other programs.  This mode of operation is 

sometimes referred to as "application modal".  When the 

Modal Dialog is showing on a Win95 system and you attempt

to perform some other operation within the program, you 

may receive an audible signal, possibly depending on how 

you have the sounds set up on your system.



A windowClosing() event listener object is instantiated 

and registered on the frame to terminate the program when

the frame is closed.  However, the Frame cannot be closed

while the Modal Dialog is showing.



The program was tested using JDK 1.1.3 running under Win95.

**********************************************************/



import java.awt.*;

import java.awt.event.*;

//=======================================================//



public class Dialog02 {

  public static void main(String[] args){

    GUI gui = new GUI();//instantiate a GUI

  }//end main

}//end class Dialog02

//=======================================================//



class GUI {

  public GUI(){//constructor

    //Instantiate a Frame object to serve as the parent of

    // two Dialog objects. Since it will be the parent, it

    // must be instantiated first.

    Frame myFrame = new Frame(

                           "Copyright 1997, R.G.Baldwin");

 

    //Create a nonModal Dialog object containing a close 

    // button with an action listener object registered 

    // on the close button.

    Dialog nonModalDialog = 

                    new Dialog(myFrame,"NonModal Dialog");

    Button nonModalCloseButn = new Button("Close");

    nonModalDialog.add(nonModalCloseButn);

    nonModalCloseButn.addActionListener(

                 new closeDialogListener(nonModalDialog));



    //Create a Modal Dialog object containing a close 

    // button with an action listener object registered on

    // the close button.    

    Dialog modalDialog = 

                  new Dialog(myFrame,"Modal Dialog",true);

    Button modalCloseButn = new Button("Close");

    modalDialog.add(modalCloseButn);

    modalCloseButn.addActionListener(

                    new closeDialogListener(modalDialog));



    //Create two Button objects to appear on the Frame 

    // object.  One Button object will show the nonModal 

    // Dialog object.  The other button will show the 

    // Modal Dialog object.  Instantiate and register 

    // action listener objects on both buttons which will

    // show the Dialog object passed in as a parameter at

    // the X/Y offset also passed in as a parameter. The

    // action listener objects also control the size of 

    // the Dialog objects.

    Button showNonModalButn = 

                        new Button("Show NonModal Dialog");

    showNonModalButn.addActionListener(

               new showDialogListener(nonModalDialog,100));

    Button showModalButn = new Button("Show Modal Dialog");

    showModalButn.addActionListener(

                  new showDialogListener(modalDialog,200));

    

    //Now finish constructing the Frame object.

    myFrame.setLayout(new FlowLayout());  

    myFrame.add(showModalButn);

    myFrame.add(showNonModalButn);

    myFrame.setSize(250,150);

    myFrame.setVisible(true);

     

    //Instantiate and register a window listener to 

    // terminate the program when the Frame is closed. 

    myFrame.addWindowListener(new Terminate());

  }//end constructor

}//end class GUI definition

//=======================================================//



//Class to provide an action listener that will show a 

// Dialog specified as a parameter at the X/Y offset also

// passed in as a parameter.  The action listener object

// also controls the size of the Dialog objects.

class showDialogListener implements ActionListener{

  Dialog aDialog;

  int Offset;

  

  //constructor

  showDialogListener(Dialog inDialog,int inOffset){

    aDialog = inDialog;

    Offset = inOffset;

  }//end constructor

  

  public void actionPerformed(ActionEvent e){

    //Following order is critical for a modal dialog.  

    aDialog.setBounds(Offset,Offset,150,100);

    aDialog.show();    

  }//end actionPerformed()

}//end class myModalActionListener

//=======================================================//



//Class to provide an action listener that will close a 

// Dialog specified as a parameter.

class closeDialogListener implements ActionListener{

  Dialog aDialog;

  

  closeDialogListener(Dialog inDialog){//constructor

    aDialog = inDialog;

  }//end constructor

  

  public void actionPerformed(ActionEvent e){

    aDialog.setVisible(false);

  }//end actionPerformed()

}//end class myModalAdtionListener

//=======================================================//



class Terminate extends WindowAdapter{

  public void windowClosing(WindowEvent e){

    System.exit(0);//terminate the program

  }//end windowClosing

}//end class Terminate

//=======================================================//

Review

Previous lessons have provided review problems and review questions to reinforce the material presented in the lesson. By the time you reach this point in your study of Java programming, you should be working at a sufficiently independent level that such review information should no longer be necessary.

Therefore, review questions and programs will rarely be provided for the remaining lessons in this set of Java programming tutorials.

-end-


These tutorials were developed by Richard Baldwin and are the copyrighted property of Richard Baldwin. You have permission to print one copy for your own use, but may not, without written permission from Richard Baldwin, redistribute the tutorial documents.

The base material in these lessons is believed by the author to be in the public domain. If you use these lessons for any purpose, you are using them at your own risk, and this author assumes no responsibility or liability for any damages that you may incur.

Java, Sun, HotJava and various other related symbols and names are registered trademarks of Sun Microsystems, Inc. Macintosh is a registered trademark of Apple Computer, Inc. OS/2 is a registered trademark of International Business Machines Corporation. Microsoft, MS-DOS, Visual Basic, Windows, Windows NT, Internet Explorer and Visual J++ are registered trademarks of Microsoft Corporation. Netscape and JavaScript are trademarks of Netscape Communications Corporation. All other trademarks and service marks that may have been inadvertently used in these lessons without proper credit being given are the property of their respective owners. If you feel that your trademark or copyright has been compromised, please notify this author immediately, and an appropriate correction to the document will be issued.


© 1996, 1997, 1998, 1999 Richard G. Baldwin