com.yospace.yae.yogi
Class YogiPopup

java.lang.Object
  |
  +--com.yospace.yae.yogi.YogiComponent
        |
        +--com.yospace.yae.yogi.YogiPopup

All Implemented Interfaces:

PopupModalRoot

public class YogiPopup

extends YogiComponent

implements PopupModalRoot

A popup component. The popup is added to the root content pane in the correct layer with respect to the popup's associated modal root pane. The showDialog static methods constitute convenience methods where the Panelet writer requires a "dialog"-style popup such as an alert, a confirm box, a text entry prompt or a "waiting"-style message.

Field Summary

static int	DIALOG_ALERT The constant used to create alert dialogs.
static int	DIALOG_CONFIRM The constant used to create confirm dialogs.
static int	DIALOG_PROMPT The constant used to create prompt dialogs.
static int	DIALOG_WAITING The constant used to create waiting dialogs.
static int	PROPERTY_COMPONENT_PARENT The property constant used for defining the parent of the popup.
static int	PROPERTY_MODAL The property constant used for defining whether the popup is modal.
boolean	usingCustomComponent Whether or not this dialog is using a custom component.

Fields inherited from class com.yospace.yae.yogi.YogiComponent

ALIGN_CENTER, ALIGN_LEFT, ALIGN_RIGHT, BORDER_DOTTED, BORDER_NONE, BORDER_PLAIN, BORDER_ROUNDED, BORDER_SOLID, COLOR_BACKGROUND, COLOR_BORDER, COLOR_FOREGROUND, FOCUS_DEFAULT, FOCUS_OFF, FOCUS_ON, PROPERTY_ALIGN, PROPERTY_BORDER_STYLE, PROPERTY_BOUNDS, PROPERTY_COLOR, PROPERTY_CONTEXT_ENABLED, PROPERTY_ENABLED, PROPERTY_FOCUS, PROPERTY_FOCUS_INDEX, PROPERTY_FOCUS_TRAVERSABLE, PROPERTY_FONT, PROPERTY_HOTKEY, PROPERTY_LOCATION, PROPERTY_OPAQUE, PROPERTY_SIZE, PROPERTY_VISIBLE, PROPERTY_X_INSET, PROPERTY_Y_INSET

Constructor Summary

YogiPopup()
Default constructor sets up the component parent to be null and the popup to be non-modal.

YogiPopup(YogiComponent componentParent, boolean modal)
This constructor should be used where possible.

Method Summary

int	getButtonPressedIndex() Accessor method for getting the button that was pressed on this dialog.
YogiComponent	getComponentParent() Accessor method for getting hold of the parent of the YogiPopup.
int	getDialogType() Accessor method for getting the type of dialog that popup is.
YogiComponent	getParent() Overrides inheritted method to always return null, thus stopping the application writer from accessing components outside of the confines of the popup.
PopupModalRoot	getPopupModalRoot() Accessor method for getting hold of the popup modal root.
void	hide() Hides the popup.
boolean	isModal() Accessor method for getting the component's modal state.
void	setComponentParent(YogiComponent c) Sets the conceptual parent of this popup to be the given component.
static void	setLayeredPane(YogiRootWindow key) Method used at startup to register the layered pane to add all popups to.
void	setModal(boolean modal) Setter method for the popup's modal state.
void	show() Displays the popup.
static void	showDialog(YogiComponent componentParent, int type, java.lang.String message, java.lang.String[] buttonText, ActionListener userDialogListener) Static convenience method which simply takes one less parameter, component, than its six argument equivalent.
static void	showDialog(YogiComponent componentParent, int type, java.lang.String message, YogiComponent component, java.lang.String[] buttonText, ActionListener userDialogListener) Static convenience method which allows for a (user configured) dialog-style popup to be displayed.

Methods inherited from class com.yospace.yae.yogi.YogiComponent

_debugPrintComponents, add, addPropertyChangeListener, bringForwards, bringInFrontOf, bringToFront, contains, containsComponent, ensureVisible, ensureVisible, findComponentAt, findCurrentFocus, findFirstFocus, findFocusDomainRoot, findFocusDomainRootImpl, findHotkeyComponent, findNextFocus, fireActionPerformedEvent, firePropertyChangeEvent, getAlign, getBorderStyle, getBounds, getColor, getColors, getComponent, getComponent, getComponentCount, getComponentIndex, getComponents, getFocusBounds, getFocusIndex, getFont, getGlobalLocation, getHeight, getHotkey, getId, getParent, getTreeLock, getUI, getWidth, getX, getXInset, getY, getYInset, hasFocus, isActive, isContextEnabled, isEnabled, isFocusDomainRoot, isFocusTraversable, isOpaque, isVisible, keyPressed, keyReleased, keyRepeated, paint, paintBackground, paintBorder, paintForeground, pointerDragged, pointerPressed, pointerReleased, remove, remove, removeAll, removePropertyChangeListener, repaint, repaint, repaintAfterRebounding, requestFocus, requestFocus, sendBackwards, sendBehind, sendToBack, setActionListener, setActive, setAlign, setBorderStyle, setBounds, setColor, setColors, setContextEnabled, setDefaultColor, setEnabled, setFocusDomainRoot, setFocusIndex, setFocusTraversable, setFont, setHotkey, setId, setLocation, setNoFocus, setOpaque, setProperty, setSize, setUI, setVisible, setXInset, setYInset, updateUI

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PROPERTY_COMPONENT_PARENT

public static final int PROPERTY_COMPONENT_PARENT

The property constant used for defining the parent of the popup.

PROPERTY_MODAL

public static final int PROPERTY_MODAL

The property constant used for defining whether the popup is modal.

DIALOG_ALERT

public static final int DIALOG_ALERT

The constant used to create alert dialogs.

DIALOG_CONFIRM

public static final int DIALOG_CONFIRM

The constant used to create confirm dialogs.

DIALOG_PROMPT

public static final int DIALOG_PROMPT

The constant used to create prompt dialogs.

DIALOG_WAITING

public static final int DIALOG_WAITING

The constant used to create waiting dialogs.

usingCustomComponent

public boolean usingCustomComponent

Whether or not this dialog is using a custom component. Used with the showDialog convenience methods.

Constructor Detail

YogiPopup

public YogiPopup()

Default constructor sets up the component parent to be null and the popup to be non-modal.

YogiPopup

public YogiPopup(YogiComponent componentParent,
                 boolean modal)

This constructor should be used where possible. The first argument specifies the component of which this popup is conceptually a child. Popups are added to the relevant layer (with respect to the component parent) of the root window's root content pane, which is a layered pane. This allows for popups to stretch beyond the bounds of their (modal) root whilst still remaining fully visible. They are added to the layered pane with respect to increased z-ordering (as with add() for other containers). The second argument sets whether the Popup is modal, i.e. whether the modal root should be disabled at show-time, to be re-enabled (if necessary) when the popup is destroyed.

Parameters:

componentParent - the conceptual parent of this component.

modal - whether the Popup is modal or not.

Method Detail

getParent

public YogiComponent getParent()

Overrides inheritted method to always return null, thus stopping the application writer from accessing components outside of the confines of the popup.

Overrides:

getParent in class YogiComponent

Returns:

null.

setLayeredPane

public static void setLayeredPane(YogiRootWindow key)

Method used at startup to register the layered pane to add all popups to. Can only be set by an Object which has a reference to the root window (the 'key').

Parameters:

key - the root window, of which the layered pane is a child.

setComponentParent

public final void setComponentParent(YogiComponent c)

Sets the conceptual parent of this popup to be the given component. This method then climbs the component hierarchy, starting at the given component, to find the first component which is a valid modal root for the popup. Such a modal root can be one of: a YogiPopup; a YogiPaneletDisplay; or the root window. Where a YogiPopup is found, we have a popup which can be seen as being generated by another popup. Where a YogiPaneletDisplay is found, we have a Panelet-level popup. Finally, where the root window is found we have a system-level popup. When the popup is shown, if that popup is modal then the associated modal root is disabled until the popup has been destroyed. Hence the term "popup modal root".

Parameters:

c - the conceptual parent of the popup.

getComponentParent

public YogiComponent getComponentParent()

Accessor method for getting hold of the parent of the YogiPopup.

Returns:

the popup's "component parent", or null if it has not been set.

getPopupModalRoot

public PopupModalRoot getPopupModalRoot()

Accessor method for getting hold of the popup modal root.

Returns:

the popup modal root, or null if it has not been set.

setModal

public void setModal(boolean modal)

Setter method for the popup's modal state.

Parameters:

modal - the modality value to set for this popup.

isModal

public boolean isModal()

Accessor method for getting the component's modal state.

Returns:

true if the popup is modal, false otherwise.

show

public void show()

Displays the popup. Adds the popup to the relevant layer of the root window layered pane. If the componentParent was not set, then the popup will not be shown. Also disables the popup modal root component sub-tree if the popup is modal.

hide

public void hide()

Hides the popup. Removes the popup from the layered pane in which it resides. If it is not a child of a layered pane then this method does nothing - it is presumed that show has not yet been called. Resets the popup modal root's enabled state back to its value before the popup was shown. A subsequent call to show() should cause the popup to be re-displayed in the state that it was just prior to the call to hide().

showDialog

public static void showDialog(YogiComponent componentParent,
                              int type,
                              java.lang.String message,
                              YogiComponent component,
                              java.lang.String[] buttonText,
                              ActionListener userDialogListener)

Static convenience method which allows for a (user configured) dialog-style popup to be displayed. Dialog types are:

• ALERT which displays an image (typically an exclamation mark), a message, and by default simply includes a button labeled "ok".
• CONFIRM which displays an image (typically a question mark), a message, and by default buttons labeled "yes", "no" and "cancel".
• PROMPT which displays a message, a text field for user entry, and by default buttons labeled "ok" and "cancel".
• WAITING which displays an image (typically an hour glass - perhaps animated), a message, and by default a button labeled "cancel".

Button text and extra custom-labeled buttons can be managed by sending an array of Strings representing the desired labels. The first x Strings in the array represent the text on the default buttons, where x is the number of default buttons associated with this dialog type. Adding entries in the String array beyond x tells the method to add extra custom buttons to the dialog. Using null in an array index represents a request to use the default string, if one exists.
When the dialog is created, all actions fired by the pressing of any of the associated buttons are caught, the firing button's index is noted, and then a centralized action event is fired from the dialog. A listener for this event can be sent to this method by the user. The code within this action listener might initially extract the button pressed index, for example by calling

((YogiPopup)source).getButtonPressedIndex();

and performing a switch on this value to decide what subsequent action to take. Once any button is pressed on the popup, the dialog is automatically removed from the screen.
A YogiComponent can also be sent to this method. If the desired dialog type is not a PROMPT dialog, and if the component given is a YogiImageComponent then this image component is used instead of the default one. Similarly, if we have a PROMPT dialog and the component is a YogiTextField then this text field is used.

Parameters:

componentParent - the component which is requesting this dialog.

type - the desired dialog type. For valid types see above.

message - the text to be displayed in the text area of the dialog.

component - a custom YogiImageComponent or YogiTextField to be used in the dialog.

buttonText - the array of Strings to be used on the generated buttons.

userDialogListener - an instance of ActionListener which is associated with the dialog, and includes action code for when each button is pressed.

Throws:

java.lang.IllegalArgumentException - if the given dialog type is invalid.

showDialog

public static void showDialog(YogiComponent componentParent,
                              int type,
                              java.lang.String message,
                              java.lang.String[] buttonText,
                              ActionListener userDialogListener)

Static convenience method which simply takes one less parameter, component, than its six argument equivalent. Simply calls #showDialog(YogiComponent, int, String, YogiComponent, String[], ActionListener) with null in component field.

Parameters:

componentParent - the component which is requesting this dialog.

type - the desired dialog type.

message - the text to be displayed in the text area of the dialog.

buttonText - the array of Strings to be used on the generated buttons.

userDialogListener - an instance of ActionListener which is associated with the dialog, and receives an event when one of the dialog's buttons is pressed.

getDialogType

public int getDialogType()

Accessor method for getting the type of dialog that popup is.

Returns:

the dialog type of the dialog. If this popup is not a dialog, -1 is returned.

getButtonPressedIndex

public int getButtonPressedIndex()

Accessor method for getting the button that was pressed on this dialog.

Returns:

the button index of the last button pressed in the dialog. If this popup is not a dialog, -1 is returned.