//++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
// J2ME-Lib source file
// Copyright (c) 2006 Elmar Sonnenschein / esoco GmbH
// Last Change: 10.11.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.util.ProgressMonitor;
import javax.microedition.lcdui.Form;
import javax.microedition.lcdui.Gauge;
import javax.microedition.lcdui.Image;
import javax.microedition.lcdui.StringItem;
/********************************************************************
* A Dialog subclass that displays information about the progress of a long
* running process. It implements the ProgessMonitor interface to receive the
* information about the progress. To make this class work correctly it is
* necessary that the monitored tasks run in separate threads instead of the
* main application thread because otherwise screen updates wouldn't be
* possible.
*
* <p>This implementation is capable of displaying itself automatically on
* initialization and to hide again if the progress counter reaches the maximum
* or if the view is reset. But even if automatic activation is enabled the
* application should correctly dispose the progress view after the monitored
* processing cycle has been completed to prevent the progress view from staying
* on the display (e.g. if lesser steps have been processed than expected). This
* should be done by invoking the method <code>reset()</code> in a try-finally
* block that surrounds the processing code to make sure that the previous
* screen is restored in any case.</p>
*
* @author eso
* @see de.esoco.j2me.util.ProgressMonitor
*/
public class ProgressView extends Form implements ProgressMonitor
{
//~ Static fields/initializers ---------------------------------------------
/** Delay in ms before the view is displayed automatically */
private static final int AUTO_ACTIVATION_DELAY = 500;
//~ Instance fields --------------------------------------------------------
private StringItem aInfo = null;
private Gauge aProgressBar;
private StringItem aProgressInfo = null;
private boolean bAutoDisplay = false;
private boolean bDisplaying = false;
private boolean bSilent = false;
private int nMax = 0;
private long nStartTime;
private int nState = 0;
//~ Constructors -----------------------------------------------------------
/***************************************
* Constructor to initialize a ProgressView instance. The maximum value is
* initially set to 100 so that calls to the method advance() based on a
* percentage scale can be invoked without a previous call to init().
*
* @param sTitle The title for the view (may but should not be
* NULL)
* @param rImage An optional image to display or NULL for no image
* @param sInfoText An optional information text or NULL
* @param bAutoShowAndHide If TRUE, the view will automatically be displayed
* when it is initialized and hidden when the
* maximum is reached
*/
public ProgressView(String sTitle,
Image rImage,
String sInfoText,
boolean bAutoShowAndHide)
{
super(sTitle);
aInfo = new StringItem(null, null);
aProgressInfo = new StringItem(null, null);
aProgressBar = new Gauge(null, false, 100, 0);
if (rImage != null)
{
append(rImage);
}
setInfoText(sInfoText);
append(aInfo);
append(aProgressBar);
append(aProgressInfo);
bAutoDisplay = bAutoShowAndHide;
}
//~ Methods ----------------------------------------------------------------
/***************************************
* Advance the progress monitor a certain number of steps.
*
* @param nSteps The number of steps to advance
*
* @see de.esoco.j2me.util.ProgressMonitor#advance(int)
*/
public void advance(int nSteps)
{
if (nState >= nMax)
{
return;
}
nState += nSteps;
if (bAutoDisplay && !bDisplaying && !bSilent)
{
long nTime = System.currentTimeMillis() - nStartTime;
// show if activation delay has been reached and no more than
// half of the announced steps have been processed
if ((nTime >= AUTO_ACTIVATION_DELAY) && (nSteps < (nMax / 2)))
{
ScreenManager.showTemporary(this);
bDisplaying = true;
}
}
if (nState >= nMax)
{
nState = nMax;
restoreScreen();
}
else if (!bSilent)
{
aProgressBar.setValue(nState);
}
}
/***************************************
* Returns the maximum number of steps the monitor is currently initialized
* for.
*
* @return The current maximum number of steps
*/
public int getMaximum()
{
return nMax;
}
/***************************************
* Returns the current progress monitor state.
*
* @return The current state
*
* @see de.esoco.j2me.util.ProgressMonitor#getState()
*/
public int getState()
{
return nState;
}
/***************************************
* Initializes the progress view. If automatic display is enabled the view
* screen will be displayed
*
* @param nMaximumSteps The maximum number of progress steps to monitor
* @param sProgressInfo An optional (short) information text describing the
* progress or NULL
*
* @see de.esoco.j2me.util.ProgressMonitor#init(int, String)
*/
public void init(int nMaximumSteps, String sProgressInfo)
{
nStartTime = System.currentTimeMillis();
nMax = nMaximumSteps;
nState = 0;
aProgressBar.setMaxValue(nMax);
aProgressBar.setValue(nState);
aProgressInfo.setText(sProgressInfo);
}
/***************************************
* To check if this view is set to automatically show and hide it's display
* screen.
*
* @return TRUE if automatic display is enabled
*/
public boolean isAutoDisplay()
{
return bAutoDisplay;
}
/***************************************
* To reset the current progress view. This will reset internal variables
* and restore the previous screen if automatic display is enabled.
*
* @see ProgressMonitor#reset()
*/
public void reset()
{
restoreScreen();
bSilent = false;
nMax = 0;
}
/***************************************
* To enable or disable automatic showing and hiding of this view's display
* screen.
*
* @param bAutoShowAndHide TRUE to enable
*/
public void setAutoDisplay(boolean bAutoShowAndHide)
{
bAutoDisplay = bAutoShowAndHide;
}
/***************************************
* Sets the displayed information text.
*
* @param sInfo The string to display or NULL to clear the current text
*/
public void setInfoText(String sInfo)
{
aInfo.setText(sInfo);
}
/***************************************
* Sets the displayed progress information text.
*
* @param sInfo The string to display or NULL to clear the current text
*/
public void setProgressInfoText(String sInfo)
{
aProgressInfo.setText(sInfo);
}
/***************************************
* To enable or disable the visual output of the view. If set to silent the
* view will not automatically display or update it's screen but the
* progress state will still be tracked. The state of this flag will be set
* to true by the <code>reset()</code> method.
*
* @param bSilent TRUE to disable the progress display
*
* @see de.esoco.j2me.util.ProgressMonitor#setSilent(boolean)
*/
public void setSilent(boolean bSilent)
{
this.bSilent = bSilent;
}
/***************************************
* Internal method to restore the screen if automatic display is enabled.
*/
protected void restoreScreen()
{
if (bDisplaying)
{
bDisplaying = false;
ScreenManager.previousTemporary();
}
}
}