Class UIMessageBox

public class UIMessageBox extends UIDialog implements 
            TimerListener
{
  // Fields
  public final static int CENTER;
  public final static int EXCLAMATION;
  public final static int INFORMATION;
  public final static int LEFT;
  public final static int QUESTION;
  public final static int RIGHT;
  public final static int STOP;

  // Constructors
  public UIMessageBox(UIFrame frame);
  public UIMessageBox(UIFrame frame, String Title, String Text, int
        image, int buttonSet);
  public UIMessageBox(UIFrame frame, String Title, String Text,
        Image image, UIButtonBar buttons);
  public UIMessageBox(UIFrame frame, String Title, String Text,
        Image Image, UIButtonBar Buttons, int Alignment,
        int Default );

  // Methods
  public boolean action(Event e, Object o);
  public void addNotify();
  public Object doModal();
  public int doModalIndex();
  public int getButtonAlignment();
  public UIButtonBar getButtons();
  public int getDefaultButton();
  public UIFrame getFrame();
  public Image getImage();
  public Insets getInsets();
  public Dimension getPreferredSize();
  public String getText();
  public int getTimeout();
  public Insets insets();
  public boolean keyDown(Event e, int key);
  public boolean keyUp(Event e, int key);
  public Dimension preferredSize();
  public void setButtonAlignment(int Align);
  public void setButtons(UIButtonBar buttons);
  public UIButtonBar setButtons(String buttons, int style);
  public void setDefaultButton(int i);
  public void setImage(int image);
  public void setImage(Image i);
  public void setText(String text);
  public void setTimeout(int time);
  public void timeTriggered(TimerEvent e);
}

This class implements a message box window. UIMessageBox enables you to generate message boxes that conform to Windows guidelines or create custom message boxes using several types of button alignments, custom buttons, and imported images. A set of predefined buttons and standard system images are supplied to make basic message box construction simple and efficient. Message boxes may only be modal.

The following example shows how to construct multiple types of message boxes:

// Construct a generic message box with the title
//"Image File Read Error", a message that informs the user
// that the file could not be opened, and an appropriate
// system-defined image.
String message = "The image file was not found, 
					or cannot be opened.";
UIMessageBox fileNotFound = new UIMessageBox(parentFrame, 
                      "File Not Found", message, UIMessageBox.STOP, 
                       UIButtonBar.RETRYCANCEL);

// Construct a message box with custom image, two buttons, and 
// LEFT button alignment.
String message2 = "VirusScan found no viruses or Trojan Horses on
                   this disk. Would you like to scan another?";

UIButtonBar VirScanButns = new UIButtonBar("Scan Another Disk,Exit",
                                           ",",
                                           UIPushButton.RAISED);

UIMessageBox ScanMe = new UIMessageBox (parentFrame,
                                        "VirusScan Ver 1.00",
                                         message2, VirScanImg,
                                         VirScanButns, 
                                         UIMessageBox.RIGHT, -1);

// You can also construct an initially empty message box and 
// populate it using the setText, setImage, setButtons,
// and setButtonAlignment methods.
UIMessageBox myEmptyBox = new UIMessageBox(parentFrame);

// Call the Dialog class setTitle method.
myEmptyBox.setTitle("DiskCopy");

// Set the message that is displayed by the message box.
myEmptyBox.setText("Copy complete.");

// Use a pre-defined image for the message box.
myEmptyBox.setImage(UIMessageBox.INFORMATION);

// Because this is an information box, we need only
// supply an OK button for the end user.
myEmptyBox.setButtons(new UIButtonBar("OK", 
                                  UIPushButton.RAISED));

// Set the button so that it is aligned in the center of 
// the message box.
myEmptyBox.setButtonAlignment(UIMessageBox.CENTER);

UIMessageBox objects may be automatically dismissed when associated with a timer. Use the setTimeout method to set the length of time the message box should be displayed and call the doModal method as you normally would. The following example shows you how to set a timed modal message box.

// The myEmptyBox message box created in the previous example 
// can be used as a timed, informative message box that requires 
// no end user interaction. The message box is still constructed
// in the same way, but it will be displayed for 3 seconds, and then 
// automatically  destroyed when the timeTriggered 
// method is called.
myEmptyBox.setTimeout(3000);

myEmptyBox.doModal();

The com.ms.fx package provides classes that manage the system images and fonts typically used in message and dialog boxes, as well as four standard system images in .gif file format. See the FxSystemIcon and FxSystemFont classes for more information.

UIComponent
  |
  +--UIContainer
    |
    +--UIStateContainer
      |
      +--UIPanel
        |
        +--UIRoot
          |
          +--UIWindow
            |
            +--UIDialog
              |
              +--UIMessageBox

Constructors

UIMessageBox

public UIMessageBox(UIFrame frame);

Creates a message box with no title, text, image, or buttons. By default, the message box is center aligned.

Parameter	Description
frame	The parent container to attach the message box to.

UIMessageBox

public UIMessageBox(UIFrame frame, String Title, String Text, int image,
        int buttonSet);

Creates a message box with specified title, text, pre-defined image, and buttons. By default, the message box is center aligned.

Parameter	Description
frame	The parent container to attach the message box to.
Title	The title of the message box.
Text	The message that is displayed in the message box.
image	An index to one of 4 default images or zero. The images may be one of the following: STOP QUESTION EXCLAMATION INFORMATION
buttonSet	One of the predefined sets of buttons in UIButtonBar.

UIMessageBox

public UIMessageBox(UIFrame frame, String Title, String Text, Image image,
        UIButtonBar buttons);

Creates a message box with specified title, text, image, and buttons. By default, the message box is center aligned. This constructor enables you to use custom images for your message boxes and sets of UIPushButton objects wrapped by a UIButtonBar object.

Parameter	Description
frame	The parent container to attach the message box to.
Title	The title of the message box.
Text	The message that is displayed in the message box.
image	The imported image displayed to the left of the text in the message box.
buttons	A UIButtonBar object that contains the buttons for the message box.

UIMessageBox

public UIMessageBox(UIFrame frame, String Title, String Text, Image Image,
        UIButtonBar Buttons, int Alignment, int Default );

Creates a message box with the specified title, text, imported image, buttons, and alignment. You can also specify a default button with this constructor.

Parameter	Description
frame	The parent container to attach the message box to.
Title	The title of the message box.
Text	The message that is displayed in the message box.
Image	The imported image displayed to the left of the text in the message box.
Buttons	A UIButtonBar object that contains the buttons for the message box.
Alignment	The alignment of the buttons in the message box. By default this is CENTER, but it may also be LEFT or RIGHT.
Default	A specified default button or -1 for no default.

Methods

action

public boolean action(Event e, Object o);

Performs operations depending on which button inside the message box was pushed.

Note When cancelling the dialog, the method calls UIDialog.dispose.

Return Value:

Returns true if the action was successfully executed; otherwise, returns false.

Parameter	Description
e	The event, such as a KEY_RELEASE or MOUSE_UP, generated within the message box.
o	The button that was pushed.

addNotify

public void addNotify();

Called to perform initialization when the graphics context is first available.

Return Value:

No return value.

Remarks:

This method initializes the font of the message box. The font's style is set to PLAIN, and the size is set to 8 points. addNotify also adds the button bar, image, and text components to the message box.

doModal

public Object doModal();

Displays the message box as a modal message box and retrieves the button that is pressed. The message box can also be automatically destroyed by using an associated timer.

Return Value:

Returns the pressed button. Use the getID method to retrieve the button's identifier and compare that to the UIButtonBar used to construct the message box.

Remarks:

A modal message box requires the user to interact with the message box before continuing in any other of the application's windows.

See Also: setTimeout, getTimeout, timeTriggered

doModalIndex

public int doModalIndex();

Displays the message box as a modal message box and retrieves the index of the button that is pressed.

Return Value:

Returns the index of the pressed button; returns -1 if the message box is cancelled.

Remarks:

A modal message box requires the user to interact with the message box before continuing in any other of the application's windows.

getButtonAlignment

public int getButtonAlignment();

Retrieves the current alignment of the buttons in the message box.

Return Value:

Returns either a CENTER, LEFT, or RIGHT alignment flag.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

See Also: setButtonAlignment

getButtons

public UIButtonBar getButtons();

Retrieves the UIButtonBar object that contains the buttons for the message box.

Return Value:

Returns the UIButtonBar object that contains the buttons for the message box.

See Also: setButtons

getDefaultButton

public int getDefaultButton();

Retrieves the index of the UIButtonBar object that is used for default buttons in message boxes.

Return Value:

Returns the index of the UIButtonBar object that is set as the default button.

getFrame

public UIFrame getFrame();

Retrieves the parent container associated with the message box.

Return Value:

Returns a UIFrame object that is the parent for the message box.

getImage

public Image getImage();

Retrieves the image displayed in the message box.

Return Value:

Returns the Image displayed in the message box. Returns null if no image is associated with the message box.

getInsets

public Insets getInsets();

Retrieves the insets of the message box.

Return Value:

Returns an object containing the insets for the message box.

See Also: insets

getPreferredSize

public Dimension getPreferredSize();

Retrieves the preferred dimensions (in pixels) for displaying the control.

Return Value:

Returns a Dimension object with a width and height of 0 pixels.

getText

public String getText();

Retrieves the text that the message box displays.

Return Value:

Returns a String buffer that contains the message displayed in the message box.

See Also: setText

getTimeout

public int getTimeout();

Retrieves the length of time that the message box is displayed, when associated with a timer.

Return Value:

Returns the length of time that the message box is displayed.

See Also: setTimeout, timeTriggered

insets

public Insets insets();

Determines the insets of the message box.

Return Value:

Returns the Insets object containing the insets.

keyDown

public boolean keyDown(Event e, int key);

Responds to a key being pressed when the message box has focus.

Return Value:

Returns true if the event was successfully handled; otherwise, returns false.

Parameter	Description
e	The event posted to the message box.
key	The key that has been pressed.

Remarks:

This method checks for the ENTER or SPACEBAR keys, which indicate a button has been depressed (a choice may be made). The method similarly responds to the ESCAPE key. Otherwise, the superclass handles the keyDown method.

Overrides:

keyDown(Event,int) in UIDialog.

keyUp

public boolean keyUp(Event e, int key);

Responds to a key being released when the message box has focus.

Return Value:

Returns true if the event was successfully handled; otherwise, returns false.

Parameter	Description
e	The event posted to the message box.
key	The key that has been released.

Remarks:

This method checks for the ENTER and SPACEBAR keys, which indicate a button has been pressed and released, and closes the window. The ESCAPE key closes the window if the message box is not a modal message box and a choice does not need to be made. Otherwise, the superclass handles the keyUp method.

Overrides:

keyUp(Event,int) in UIDialog.

preferredSize

public Dimension preferredSize();

Calculates the minimum size of a message box. The minimum size is limited to one-sixth the screen width.

Return Value:

Returns a Dimension object containing the preferred size, in pixels.

setButtonAlignment

public void setButtonAlignment(int Align);

Sets the button alignment in the message box.

Return Value:

No return value.

Parameter	Description
Align	The button alignment. Possible values include CENTER, LEFT, or RIGHT.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

See Also: getButtonAlignment

setButtons

public void setButtons(UIButtonBar buttons);

Sets the buttons that are displayed at the bottom of the message box.

Return Value:

No return value.

Parameter	Description
buttons	The buttons that are displayed.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

setButtons

public UIButtonBar setButtons(String buttons, int style);

Sets the button that is displayed at the bottom of the message box using a string for the button name.

Return Value:

Returns a UIButtonBar with a button of the given name.

Parameter	Description
buttons	The name of the button.
style	The button's style. This may be either FLAT or RAISED.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

setDefaultButton

public void setDefaultButton(int i);

Sets the given UIButtonBar index as the default buttons created with a message box.

Return Value:

No return value.

Parameter	Description
i	The index of the button associated with the UIButtonBar. Set this parameter to -1 if you don't want to set a default button for the UIButtonBar.

setImage

public void setImage(int image);

Sets the image that is displayed to the left of the message box as one of four predefined types.

Return Value:

No return value.

Parameter	Description
image	The image to use in the message box. This may be one of the following images: STOP QUESTION EXCLAMATION INFORMATION

setImage

public void setImage(Image i);

Sets the image that is displayed to the left of the message box.

Return Value:

No return value.

Parameter	Description
i	The imported image to use in the message box.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

setText

public void setText(String text);

Sets the message that the message box displays.

Return Value:

No return value.

Parameter	Description
text	The text in the message box.

Remarks:

This method is used when the default UIMessageBox constructor has been called and no buttons have been added to the message box.

See Also: getText

setTimeout

public void setTimeout(int time);

Sets a timer used to display the message box for a certain amount of time.

Return Value:

No return value.

Parameter	Description
time	The amount of time that the message box is displayed (in milliseconds).

See Also: getTimeout, timeTriggered

timeTriggered

public void timeTriggered(TimerEvent e);

Posts a window destroy event to the message box object.

Return Value:

No return value.

Parameter	Description
e	A TimerEvent object that is timing the message box.

Remarks:

This method implements timeTriggered in the TimerListener interface.

Note if you extend your own class from UIMessageBox and implement the TimerListener interface, be sure to call the super method TimerListener(event).

See Also: setTimeout, getTimeout, com.ms.util.TimerListener

Fields

CENTER

The buttons are centered in the message box.

EXCLAMATION

The image used in message boxes when a warning message is displayed.

INFORMATION

The image used in message boxes when an information message is displayed.

LEFT

The buttons are aligned on the left side of the message box.

QUESTION

The image used to query a user. This image is no longer commonly used on the Microsoft® Win32® platform.

RIGHT

The buttons are aligned on the right side of the message box.

STOP

The image used in message boxes when a critical message is displayed.