de.frame4j.graf

Class AskDialog

java.lang.Object

de.frame4j.graf.AskDialog

All Implemented Interfaces:

ActionListener, KeyListener, EventListener, DocumentListener

@MinDoc(copyright="Copyright 1998 - 2009, 2014  A. Weinert",
        author="Albrecht Weinert",
        version="V.56",
        lastModified="28.06.2021",
        usage="construct and get answer (or static getAnswer)",
        purpose="dialog or info window with timeout")
public class AskDialog
extends Object
implements ActionListener, KeyListener, DocumentListener

A dialog window for common use.

For intermediate displays and interposed questions graphical applications as well as non graphical ones often need a dialogue window. Usually this consists of one or two texts (may be one of it with input facilities) and up to three buttons to get user responses. Figure 1 shows an example. With the options mentioned the majority of use cases is covered.
Figure 1: Simple example of an AskDialog window.

Objects of this class are that kind of dialogue window featuring thread and event handling and hence giving all comfort to the using class. Compared to a JOptionPane used often in similar use cases the main differences are:

• - less flexibility in graphical layout,
• + less difficult handling,
• + optional limiting the wait time for user responses (as the time-out feature is often badly needed),
• + does not (contrary to JOptionPane) forbid the normal usage and ending of a (non graphical) application.

Remark: Normal ending means a well behaved end of all threads without "violence" like System.exit(); see Hint 1. Applications, using AskDialog objects don't get exit() problems, even if non graphical and also if not Frame4J or App based.

Hint 1: Also with non graphical applications having used graphical elements the JVM has to be killed with System.exit() sometimes. The reason is the (buggy) running of graphical event threads as non daemons even if the last usage / life / visibility of graphical elements was hours ago. On the other hand calling System.exit() in one thread too early may have disastrous effects on server applications as undeniably killing all running threads. Frame4J organises the JVM end for all applications based on it (on App) safely.

Hint 2: Depending on the construction with or without parent window, the used dialogue window is made as JDialog respectively as JFrame (the common grandma is Window). As the event handling of Dialogs is problematic on some platforms the usage of Frames should be preferred.

Hint 3: The response code values YES, NO etc. differ from those of JOptionPane.


© Copyright 1998 - 2002, 2004 Albrecht Weinert

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AskDialog.Listener Listener for AskDialog.

Field Summary

Fields

Modifier and Type	Field and Description
protected int	answer The answer.
protected char[]	answerText The answer line.
Color	bg The dialogue's background colour.
static int	CANCEL Response value.
static int	CLOSED Response value.
protected AskDialog.Listener	listener The maximal one Listener.
int	maxWait Maximum wait time (in tenth of second) for human answer.
protected int	minHeigth Minimal height.
protected int	minWidth Minimal width.
boolean	modal Is it a modal Dialog or JDialog.
boolean	multipleUse Multiple usage of this object and of the dialogue.
static int	NO Response value.
static int	NOT_YET Response value.
boolean	passWordHide Password entry.
Window	theDialog The dialogue window.
static int	YES Response value.

Constructor Summary

Constructors

Constructor and Description
AskDialog(Object parent, String title, boolean modal, CharSequence upper, CharSequence yes, CharSequence cancel, CharSequence no, CharSequence lower) Constructor with parent window / object.
AskDialog(String title, CharSequence upper, CharSequence yes, CharSequence cancel, CharSequence no, CharSequence lower) Parent-less Constructor.

Method Summary

Modifier and Type	Method and Description
void	actionPerformed(ActionEvent event) Execution of button commands.
void	addListener(AskDialog.Listener listener) Register an answer Listener.
static String	answerAsText(int answer) Response (code) as text.
void	changedUpdate(DocumentEvent e) Changes in entry fields.
static void	clearChars(char[] ca) Clearing a char[].
void	dispose() Give up this AskDialog object and free all resources.
int	getAnswer() Wait for answer.
static int	getAnswer(String title, CharSequence upper, boolean upperMonospaced, CharSequence yes, CharSequence cancel, CharSequence no, int waitMax, CharSequence lower, Color bg) One time (parent-less) button inquiry.
int	getAnswer(String upper, String lower) Wait for answer after setting new display texts.
String	getAnswerText() Wait for answer without setting new display texts.
static char[]	getAnswerText(String title, CharSequence upper, boolean upperMonospaced, CharSequence yes, CharSequence cancel, int waitMax, CharSequence lower, Color bg, boolean passWordHide) One time (parent-less) text inquiry.
char[]	getAnswerText(String upper, String lower, boolean passWordHide) Wait for answer after setting new display texts.
protected String	getLab2String() The (if given) lower text field's text.
protected char[]	getLab2Text() The (if given) lower text field's text.
int	getMinHeigth() Minimal height.
int	getMinWidth() Minimal width.
void	insertUpdate(DocumentEvent e) Changes in entry fields.
void	keyPressed(KeyEvent event) Execution of button commands.
void	keyReleased(KeyEvent e) Execution of button commands.
void	keyTyped(KeyEvent e) Execution of button commands.
void	removeUpdate(DocumentEvent e) Changes in entry fields.
void	setMinHeigth(int minHeigth) Minimal height.
void	setMinWidth(int minWidth) Minimal width.
void	setUpperMonospaced() Set the font for the upper text as non proportional.
void	setVisible(String upper, String lower) Make visible without waiting for answer.

Methods inherited from class java.lang.Object

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

Field Detail

NOT_YET

public static final int NOT_YET

Response value.

No response yet or timed out.
Value: -1

See Also:

answer, maxWait, getAnswer(), Constant Field Values

CLOSED

public static final int CLOSED

Response value.

Window was closed (by X or Icon-Menu).
Value: -2

See Also:

answer, Constant Field Values

CANCEL

public static final int CANCEL

Response value.

Value: 0

See Also:

answer, Constant Field Values

NO

public static final int NO

Response value.

Value: 1

See Also:

answer, Constant Field Values

YES

public static final int YES

Response value.

Value: 2

See Also:

answer, Constant Field Values

minWidth

protected int minWidth

Minimal width.

default: 310 pixel

minHeigth

protected int minHeigth

Minimal height.

default: 60 pixel

theDialog

public final Window theDialog

The dialogue window.

The dialogue window use is a JDialog or a JFrame. This is decided finally at construction.

See Also:

modal

modal

public final boolean modal

Is it a modal Dialog or JDialog.

true, if theDialog is of type Dialog and if modal behaviour was ordered at construction.

answer

protected volatile int answer

The answer.

Value		Meaning
-2	CLOSED	window was explicitly closed (by X oder icon menu).
-1	NOT_YET	No response yet or timed out.
0	CANCEL	Cancel / middle button
+1	NO	No / right button
+2	YES	Yes / left button

See Also:

getAnswer(), getAnswer(String, String), getAnswer()

answerText

protected volatile char[] answerText

The answer line.

The lower text line (if given) is edible.

If there is a lower text and a Yes/OK button, the clicking of this button transfers the actual lower line's content here. Otherwise answerText will be set null.

See Also:

getAnswer()

multipleUse

public boolean multipleUse

Multiple usage of this object and of the dialogue.

If this control flag is set true, a given response just makes the window invisible without destroying it. The AskDialog object may be then re-used.

Should / can be set to false before the (very) last usage.

default: false

bg

public Color bg

The dialogue's background colour.

If set non null, the value is used as background colour for the window and both texts.

default: ColorVal.dsi (dark silver)

maxWait

public int maxWait

Maximum wait time (in tenth of second) for human answer.

This control variable determines the maximum waiting time for user's response for methods like getAnswer(). A value >= 50 is used, the unit being 1/10 second. A value < 50 means endless waiting in the thread having called getAnswer().

default: 0 (endless wait)

passWordHide

public boolean passWordHide

Password entry.

If true input into the lower text filed displays sharps (#) instead of echoing the actual input, as soon as the first modification is made.

default: false

listener

protected AskDialog.Listener listener

The maximal one Listener.

Constructor Detail

AskDialog

public AskDialog(Object parent,
                 String title,
                 boolean modal,
                 CharSequence upper,
                 CharSequence yes,
                 CharSequence cancel,
                 CharSequence no,
                 CharSequence lower)

Constructor with parent window / object.

An AskDialog object is made according to the parameters. Single graphical elements may be omitted by having the corresponding parameter null.

The dialogue made is fully prepared but keeps invisible. The querying of a user answer or response may then be made by calling the method getAnswer() (as one possibility).

Parameter parent may be null. In this case a JFrame will be generated as dialogue window.

A parameter parent non null may be of type Frame, Dialog or App. If parent is or has a window, a modal dialogue is made and placed in the parent window's upper left corner. Without a determinable parent window a JFrame will be made.

Parameters:

parent - the parent (window); of type Frame, Dialog, App, String or null

title - the title for this dialogue. if null and parent of type App App.title is used.

modal - true blocks the parent window (if given) until the closing of this dialogue

upper - upper display line(s) (or null)

yes - the left (Yes) button's label (or null)

cancel - the middle (Cancel) button's label (or null)

no - the right (No) button's label (or null)

lower - lower display line (or null)

AskDialog

public AskDialog(String title,
                 CharSequence upper,
                 CharSequence yes,
                 CharSequence cancel,
                 CharSequence no,
                 CharSequence lower)

Parent-less Constructor.

An AskDialog object is made according to the parameters. Single graphical elements may be omitted by having the corresponding parameter null.

This is equivalent to
AskDialog(null, title, false, upper, yes, cancel, no, lower)

Parameters:

title - the title for this dialogue.

upper - upper display line(s) (or null)

yes - the left (Yes) button's label (or null)

cancel - the middle (Cancel) button's label (or null)

no - the right (No) button's label (or null)

lower - lower display line (or null)

Method Detail

getAnswer

public static int getAnswer(String title,
                            CharSequence upper,
                            boolean upperMonospaced,
                            CharSequence yes,
                            CharSequence cancel,
                            CharSequence no,
                            int waitMax,
                            CharSequence lower,
                            Color bg)

One time (parent-less) button inquiry.

This is the most common static helper method to get user responses (as button clicks). It encapsulates the making of a AskDialog object for one time usage and the waiting for an answer in the calling thread, guarded by settable time-out.

Parameters:

title - the title for this dialogue.
if null and parent is of type App, the App's title App.title is used.

upper - upper display line(s) (or null)

yes - the left (Yes) button's label (or null)

cancel - the middle (Cancel) button's label (or null)

no - the right (No) button's label (or null)

lower - lower display line (or null)

upperMonospaced - true means an upper text is displayed by a non proportional font

bg - background colour (or null meaning platform standard)

Returns:

response; see upper table

See Also:

getAnswer(), setUpperMonospaced(), AskDialog(Object, String, boolean, CharSequence, CharSequence, CharSequence, CharSequence, CharSequence)

getAnswerText

public static char[] getAnswerText(String title,
                                   CharSequence upper,
                                   boolean upperMonospaced,
                                   CharSequence yes,
                                   CharSequence cancel,
                                   int waitMax,
                                   CharSequence lower,
                                   Color bg,
                                   boolean passWordHide)

One time (parent-less) text inquiry.

This static helper method encapsulates the making of a AskDialog object for one time usage and the waiting for an answer in the calling thread, guarded by adjustable time-out.

It returns the lower text that may be edited by the user, if the user closes the window by the Yes/OK button; otherwise null.

If yes and lower are null, null is returned at once as consequence.

Parameters:

title - the title for this dialogue.
if null and parent is of type App, the App's title App.title is used.

upper - upper display line(s) (or null)

yes - the left (Yes) button's label (or null)

cancel - the middle (Cancel) button's label (or null)

lower - lower display line (or null)

upperMonospaced - true means an upper text is displayed by a non proportional font

bg - background Color (or null meaning platform standard)

passWordHide - see passWordHide

Returns:

upper may be edited by the user or null

See Also:

getAnswer(), setUpperMonospaced(), AskDialog(Object, String, boolean, CharSequence, CharSequence, CharSequence, CharSequence, CharSequence), clearChars(char[])

clearChars

public static void clearChars(char[] ca)

Clearing a char[].

This method clears all elements of the passed char array (to (char)0).

The use case is the clearing of character arrays used for password input and storage after use. This is recommended after using getAnswerText(String, CharSequence, boolean, CharSequence, CharSequence, int, CharSequence, Color, boolean) for password input for security.

Hint: This possibility is the background of the often seen usage of char[] instead of String with passwords. Strings leave by nature "non erasable" traces in memory.

answerAsText

public static String answerAsText(int answer)

Response (code) as text.

Translates the response values defined here to corresponding short English texts "yes", "no", "cancel", "time out / no answer" respectively "closed".
Unknown parameter values return " ?? ".

See Also:

answer

getMinWidth

public int getMinWidth()

Minimal width.

default: 310 pixel

getMinHeigth

public int getMinHeigth()

Minimal height.

default: 60 pixel

setMinWidth

public void setMinWidth(int minWidth)

Minimal width.

Range: 100 .. 2800 pixel
default: 310

setMinHeigth

public void setMinHeigth(int minHeigth)

Minimal height.

Range: 55 .. 1090 pixel
default: 60

getLab2Text

protected char[] getLab2Text()

The (if given) lower text field's text.

Internal helper method.

getLab2String

protected String getLab2String()

The (if given) lower text field's text.

Internal helper method.

setUpperMonospaced

public void setUpperMonospaced()

Set the font for the upper text as non proportional.

Setting the font of upper text mono-spaced is usually better to display file or directory names.

default: false (hence proportional)

addListener

public void addListener(AskDialog.Listener listener)

Register an answer Listener.

To wait without blocking for response or timeout (just) one AskDialog.Listener object might be registered. To de-register this method is to be called with null.
The Listener's method askAnswered() is called in an extra helper thread. So there are no restrictions whatsoever on what an how much might be done in this method.

getAnswer

public int getAnswer()

Wait for answer.

This method makes the window visible and waits for for its "end" by means of the underlying graphical system (like Window's X or icon menu) or by one of the (max.) three buttons.

A button may be pressed by a pointing device (usually a mouse) or selected by keyboard buttons [Tab] [Back-Tab] and then be presses by keyboard's return [Enter] key, if the window has the focus.

If the control variable maxWait is set accordingly, the waiting for one of these events will be limited. If this time out happens this method returns NOT_YET as event code. Without time-out this method will wait "forever" (blocking the caller's thread).

Returns:

The code for the ending event(see answer)

See Also:

getAnswer(String, String), getAnswerText(), getAnswerText(String, String, boolean)

getAnswer

public int getAnswer(String upper,
                     String lower)

Wait for answer after setting new display texts.

Apart from the newly setting of the texts, this method is equivalent to getAnswer().

The setting of the texts happens only, if the window is not yet visible.

Parameters:

upper - If the AskDialog was made with an upper Text and this parameter is not null, the upper text is set newly.

lower - the same for the lower text

See Also:

getAnswerText(), getAnswer()

getAnswerText

public char[] getAnswerText(String upper,
                            String lower,
                            boolean passWordHide)

Wait for answer after setting new display texts.

This method is equivalent to getAnswer(upper, lower) except for returning the actual lower text, perhaps been edited by the user, if the Window was closed by clicking the left Yes/OK button. If closed otherwise or timed out null will be returned.

If this AskDialog was generated for one time usage and already closed this method returns the same value if called again.

Parameters:

upper - If the AskDialog was made with an upper Text and this parameter is not null, the upper text is set newly.

lower - the same for the lower text

See Also:

getAnswer(), getAnswer(String, String), getAnswerText()

getAnswerText

public final String getAnswerText()

Wait for answer without setting new display texts.

This is equivalent to getAnswerText(null, null, false) with transforming the returned value to a String.

See Also:

getAnswer(), getAnswer(String, String)

setVisible

public void setVisible(String upper,
                       String lower)

Make visible without waiting for answer.

This method makes the window visible.
If the window is already visible nothing is done.

The answer may be checked cyclicly, getAnswer() may be called (later) or a AskDialog.Listener added by addListener() may be informed.

Parameters:

upper - If the AskDialog was made with an upper Text and this parameter is not null, the upper text is set newly.

lower - the same for the lower text

dispose

public void dispose()

Give up this AskDialog object and free all resources.

This object and its windows may be used multiple times (saving resources for questions or reports predictably repeated), if multipleUse is set true prior to first use. In this case (only) this object holds graphical resources and threads. So its recommended (and sometimes necessary) to free those after last use.

actionPerformed

public void actionPerformed(ActionEvent event)

Execution of button commands.

Internal event handling.

Specified by:

actionPerformed in interface ActionListener

keyTyped

public void keyTyped(KeyEvent e)

Execution of button commands.

Internal event handling.

Specified by:

keyTyped in interface KeyListener

keyReleased

public void keyReleased(KeyEvent e)

Execution of button commands.

Internal event handling.

Specified by:

keyReleased in interface KeyListener

keyPressed

public void keyPressed(KeyEvent event)

Execution of button commands.

Internal event handling.
Reaction to return key for selected button.

Specified by:

keyPressed in interface KeyListener

changedUpdate

public final void changedUpdate(DocumentEvent e)

Changes in entry fields.

Specified by:

changedUpdate in interface DocumentListener

insertUpdate

public final void insertUpdate(DocumentEvent e)

Changes in entry fields.

The event is only used to hide entries to a field if used for passwords to be hidden.

Specified by:

insertUpdate in interface DocumentListener

removeUpdate

public final void removeUpdate(DocumentEvent e)

Changes in entry fields.

Specified by:

removeUpdate in interface DocumentListener