//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
// J2ME-Lib source file
// Copyright (c) 2006 Elmar Sonnenschein / esoco GmbH
// Last Change: 10.12.2006 by eso
//
// J2ME-Lib is free software; you can redistribute it and/or modify it under
// the terms of the GNU Lesser General Public License as published by the Free
// Software Foundation; either version 2.1 of the License, or (at your option)
// any later version.
//
// J2ME-Lib is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
// A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
// details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with J2ME-Lib; if not, write to the Free Software Foundation, Inc.,
// 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA or use the contact
// information from the GNU website http://www.gnu.org
//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
package de.esoco.j2me.ui;
import de.esoco.j2me.midlet.BasicMidlet;
import de.esoco.j2me.resource.ResourceBundle;
import de.esoco.j2me.util.Executable;
import javax.microedition.lcdui.Alert;
import javax.microedition.lcdui.AlertType;
import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Image;
import javax.microedition.lcdui.ImageItem;
import javax.microedition.lcdui.Item;
import javax.microedition.lcdui.TextField;
/********************************************************************
* This Class implements simple message box forms with automatic command
* handling and standard commands Ok and Cancel. To use this class it is
* mandatory that the application MIDlet is subclassed from the BasicMidlet
* class from this library because it provides the necessary infrastructure for
* resource and display access.
*
* @author eso
*/
public class MessageScreen extends Dialog
{
//~ Constructors -----------------------------------------------------------
/***************************************
* Internal constructor to setup a MessageScreen dialog instance. It is used
* by the static methods of this class.
*
* @param rDisplayable The object to be displayed by the dialog
* @param rCommands The commands ("Buttons") that can be invoked when
* the dialog is displayed or null for the default
* "Ok/Cancel"
* @param rInvokeOnConfirm The executable to be invoked after the dialog has
* been confirmed
*
* @see Dialog#Dialog(Displayable, Command[], boolean)
*/
protected MessageScreen(Displayable rDisplayable,
Command[] rCommands,
Executable rInvokeOnConfirm)
{
super(rDisplayable, rCommands, true);
setDialogListener(rInvokeOnConfirm);
}
//~ Methods ----------------------------------------------------------------
/***************************************
* Prepares a {@link Form} instance that can be used by the static
* MessageScreen methods for their display.
*
* @param sTitle The title of the form
* @param rImage An image to display (Image or String) or NULL for none
* @param sText An information text to display or NULL for none
* @param rItems Optional items to append to the form or NULL for none
*
* @return A Form instance containing the given elements
*/
public static Form setupForm(String sTitle,
Object rImage,
String sText,
Item[] rItems)
{
Form aForm = new Form(sTitle);
int nLayout = ImageItem.LAYOUT_CENTER | ImageItem.LAYOUT_NEWLINE_AFTER;
if (rImage != null)
{
Image rImg;
if (rImage instanceof Image)
{
rImg = (Image) rImage;
}
else if (rImage instanceof String)
{
rImg = ResourceBundle.getCurrent().getImage((String) rImage);
}
else
{
throw new IllegalArgumentException("Invalid image argument: " +
rImage);
}
if (rImg != null)
{
aForm.append(new ImageItem(null, rImg, nLayout, null));
}
}
if (sText != null)
{
aForm.append(sText);
}
if (rItems != null)
{
for (int i = 0; i < rItems.length; i++)
{
aForm.append(rItems[i]);
}
}
return aForm;
}
/***************************************
* Displays a message which has to be dismissed by pressing a button. This
* method is based on the {@link Alert} class of the J2ME lcdui package.
*
* @param sTitle The title of the dialog
* @param sText The information text to display
* @param rType An AlertType instance defining the type of messages
*/
public static void showAlert(String sTitle, String sText, AlertType rType)
{
Alert aInfo = new Alert(sTitle, sText, null, rType);
aInfo.setTimeout(Alert.FOREVER);
BasicMidlet.getDisplay().setCurrent(aInfo);
}
/***************************************
* Displays a confirmation dialog that allows the user to confirm or cancel
* a request. The application will be informed of a successful confirmation
* (Ok/Yes selected) by an invocation of the given Executable object.
*
* @param sTitle The title of the dialog or NULL for the default
* @param sText The information Text to display
* @param bYesNo If TRUE "Yes/No" options will be displayed
* instead of the"Ok/Cancel" default
* @param rInvokeOnConfirm The executable object that will be invoked if the
* dialog is confirmed (= Ok/Yes selected)
*/
public static void showConfirmation(String sTitle,
String sText,
boolean bYesNo,
Executable rInvokeOnConfirm)
{
Command[] aCommands = null;
if (sTitle == null)
{
sTitle = ResourceBundle.getCurrent().getString("JL_MtConfirm");
}
if (bYesNo)
{
aCommands = getYesNoCommands();
}
MessageScreen aBox = new MessageScreen(setupForm(sTitle, "Img.Question",
sText, null),
aCommands, rInvokeOnConfirm);
aBox.show();
}
/***************************************
* Displays a dialog with an error message. The dialog has only a single
* confirmation command ("Ok"). The application can optionally assign a
* dialog listener to be invoked after the command has been selected. This
* can be used, for example, to terminate the application after the user
* acknowledged a fatal error.
*
* @param sTitle The title of the dialog or NULL for the default
* @param sText The error text to display
* @param rInvokeAfter The executable object to be invoked after the user
* dismisses the dialog with the "Ok" command or NULL
* for none
*/
public static void showError(String sTitle,
String sText,
Executable rInvokeAfter)
{
if (sTitle == null)
{
sTitle = ResourceBundle.getCurrent().getString("JL_MtError");
}
Command rCmd = new Command(ResourceBundle.getCurrent().getString("Ok"),
Command.OK, 1);
MessageScreen aBox = new MessageScreen(setupForm(sTitle, "Img.Error",
sText, null),
new Command[] { rCmd },
rInvokeAfter);
aBox.bIgnoreFirstCommand = false;
aBox.show();
}
/***************************************
* Displays an input dialog that allows the user to input data into a text
* field. The resulting string can be queried by the listener with the
* {@link #getResult()} method on the Dialog object which it receives as the
* argument to it's {@link Executable#execute(Object) execute()} method. The
* result value will always be a String object.
*
* @param sTitle The title of the dialog or NULL for the default
* @param sLabel The input field label or NULL for the default
* @param sText The Text to edit in the input field (NULL for
* empty field)
* @param nMaxSize The maximum size of the text input (> 0)
* @param nConstraints One of the input constraints defined in the class
* {@link TextField}
* @param bVerify TRUE if a second input field for input
* verification shall be displayed. This is mainly
* useful for the TextField.PASSWORD constraint. If
* the two input values do not match or have zero
* length the result of the input dialog will be
* NULL
* @param rInvokeOnConfirm The executable object that will be invoked if the
* dialog is confirmed (= Ok pressed)
*/
public static void showInput(String sTitle,
String sLabel,
String sText,
int nMaxSize,
int nConstraints,
final boolean bVerify,
Executable rInvokeOnConfirm)
{
Item[] aItems = new Item[(bVerify ? 2 : 1)];
final TextField aValueField;
final TextField aVerifyField;
if (sTitle == null)
{
sTitle = ResourceBundle.getCurrent().getString("JL_MtInput");
}
if (sLabel == null)
{
sLabel = ResourceBundle.getCurrent().getString("JL_LInput");
}
aValueField = new TextField(sLabel, sText, nMaxSize, nConstraints);
aItems[0] = aValueField;
if (bVerify)
{
sLabel = ResourceBundle.getCurrent().getString("JL_LVerify");
aVerifyField = new TextField(sLabel, null, nMaxSize, nConstraints);
aItems[1] = aVerifyField;
}
else
{
aVerifyField = null;
}
Form aForm = setupForm(sTitle, "Img.Question", null, aItems);
MessageScreen aBox = new MessageScreen(aForm, null, rInvokeOnConfirm)
{
// overloading the method finishDialog() in anonymous inner class
// to handle the return value
public Object finishDialog()
{
String sResult = aValueField.getString();
if (bVerify)
{
String sVerify = aVerifyField.getString();
if (sVerify.length() == 0 || !sVerify.equals(sResult))
{
sResult = null;
}
}
return sResult;
}
};
aBox.show();
}
/***************************************
* Displays a message box dialog with arbitrary Items on a Form and a single
* Ok command or Ok/Cancel commands that can be selected by the user. The
* only mandatory element is the title string, all other may be NULL. No
* result parsing is done by this method, the application has to analyse the
* state of the dialog's elements by itself inside the dialog listener. The
* listener will only be invoked if the user selects "Ok", not on "Cancel".
*
* @param sTitle The title of the dialog
* @param sImageKey A Resource key for an image to display or NULL
* @param sText The information Text to display or NULL
* @param rItems The Item objects to be appended to the Form or
* NULL
* @param bOkOnly If TRUE only an Ok command will be displayed,
* else both Ok and Cancel commands will be
* available
* @param rInvokeOnConfirm The executable object that will be invoked if the
* dialog is confirmed (= Ok selected)
*
* @see javax.microedition.lcdui.TextField
*/
public static void showMessageBox(String sTitle,
String sImageKey,
String sText,
Item[] rItems,
boolean bOkOnly,
Executable rInvokeOnConfirm)
{
Command[] aCommands = (bOkOnly ? new Command[] { getOkCommand() }
: null);
MessageScreen aBox = new MessageScreen(setupForm(sTitle, sImageKey,
sText, rItems),
aCommands, rInvokeOnConfirm);
aBox.show();
}
/***************************************
* Return a new array that contains the commands yes and no.
*
* @return A new Command array with the yes and no commands
*/
private static Command[] getYesNoCommands()
{
return new Command[]
{
new Command(ResourceBundle.getCurrent().getString("No"),
Command.CANCEL, 2),
new Command(ResourceBundle.getCurrent().getString("Yes"),
Command.OK, 1),
};
}
}