1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 *

    16 */

    17 package javax.microedition.lcdui;

    18 

    19 import org.eclipse.swt.graphics.Point;

    20 

    21 /**

    22  * Class representing the Gauge item.

    23  */

    24 public class Gauge extends Item

    25 {

    26     /**

    27      * Indefinite constant.

    28      */

    29     public static final int INDEFINITE = -1;

    30 

    31     /**

    32      * Continuous idle constant.

    33      */

    34     public static final int CONTINUOUS_IDLE = 0;

    35 

    36     /**

    37      * Incremental idle constant.

    38      */

    39     public static final int INCREMENTAL_IDLE = 1;

    40 

    41     /**

    42      * Continuous running constant.

    43      */

    44     public static final int CONTINUOUS_RUNNING = 2;

    45 

    46     /**

    47      * Incremental updating constant.

    48      */

    49     public static final int INCREMENTAL_UPDATING = 3;

    50 

    51     /**

    52      * If Gauge is changed, reasons for Re-layouting.

    53      */

    54 	static final int UPDATE_MAXVALUE = UPDATE_ITEM_MAX << 1;

    55 	static final int UPDATE_VALUE = UPDATE_ITEM_MAX << 2;

    56 

    57     private int maxValue;

    58     private int value;

    59     private boolean interactive;

    60 

    61     /**

    62      * Constructor.

    63      *

    64      * @param name the label.

    65      * @param interactive if its interactive.

    66      * @param maxVal the maximum value.

    67      * @param initVal the initial value.

    68      */

    69     public Gauge(String aName, boolean aInteractive, int aMaxVal, int aInitVal)

    70     {

    71         maxValue = validateMaxValue(aMaxVal, aInteractive);

    72 		value = validateValue(aInitVal, maxValue);

    73 		interactive = aInteractive;

    74         setLabel(aName);

    75     }

    76 

    77     /**

    78      * Sets value of this gauge.

    79      *

    80      * @param value New value. Must be between zero and maxvalue inclusive.

    81      */

    82     public void setValue(int aValue)

    83     {

    84         // TODO: eSWT support required

    85         /*

    86          * if Gauge state is incremental-updating and it is non-interactive and

    87          * indefinite, we should update Gauge when this method is called, but

    88          * that requires eSWT extension.

    89          */

    90         value = validateValue(aValue, maxValue);

    91         updateParent(UPDATE_VALUE);

    92     }

    93 

    94     /**

    95      * Get value.

    96      *

    97      * @return the value.

    98      */

    99     public int getValue()

   100     {

   101         return value;

   102     }

   103 

   104     /**

   105      * Set the maximum value.

   106      *

   107      * @param maxValue the maximum value.

   108      */

   109     public void setMaxValue(int aMaxValue)

   110     {

   111         int oldMaxValue = maxValue;

   112 		maxValue = validateMaxValue(aMaxValue, interactive);

   113         value = validateValue(getValue(), maxValue, oldMaxValue);

   114         updateParent(UPDATE_MAXVALUE);

   115     }

   116 

   117     /**

   118      * Get maximum value.

   119      *

   120      * @return the maximum value.

   121      */

   122     public int getMaxValue()

   123     {

   124         return maxValue;

   125     }

   126 

   127     /**

   128      * Checks if gauge is interactive.

   129      *

   130      * @return true if the Gauge is interactive.

   131      */

   132     public boolean isInteractive()

   133     {

   134         return interactive;

   135     }

   136 

   137     /**

   138      * Check maximum value validity.

   139      *

   140      * @param aMaxVal the maximum value.

   141      * @param aInteractive is interactive.

   142      * @return validated maximum value.

   143      */

   144     private int validateMaxValue(int aMaxVal, boolean aInteractive)

   145     {

   146         if((!aInteractive) && (aMaxVal == INDEFINITE))

   147         {

   148 			return aMaxVal;

   149         }

   150 

   151         if(aMaxVal <= 0)

   152         {

   153             throw new IllegalArgumentException(

   154                 MsgRepository.GAUGE_EXCEPTION_INVALID_MAXVALUE);

   155         }

   156 

   157         return aMaxVal;

   158     }

   159 

   160     /**

   161      * Check value validity.

   162      *

   163      * @param aValue the value.

   164      * @param aMaxVal the maximum value.

   165      * @return validated value.

   166      */

   167 	private int validateValue(int aValue, int aMaxVal)

   168 	{

   169 		if (aMaxVal == INDEFINITE)

   170 		{

   171 			switch (aValue)

   172 			{

   173 			case CONTINUOUS_IDLE:

   174 			case INCREMENTAL_IDLE:

   175 			case CONTINUOUS_RUNNING:

   176 			case INCREMENTAL_UPDATING:

   177 				break;

   178 			default:

   179 				throw new IllegalArgumentException();

   180 			}

   181 			return aValue;

   182 		}

   183 		else

   184 		{

   185 			return clampValue(aValue, aMaxVal);

   186 		}

   187 	}

   188 

   189     /**

   190      * Check value validity.

   191      *

   192      * @param aValue the value.

   193      * @param aNewMaxVal the new maximum value.

   194      * @param aOlddMaxVal the old maximum value.

   195      * @return validated value.

   196      */

   197 	private int validateValue(int aValue, int aNewMaxVal, int aOlddMaxVal)

   198 	{

   199 		if (aNewMaxVal == INDEFINITE)

   200 		{

   201 			return CONTINUOUS_IDLE;

   202 		}

   203 		else if (aOlddMaxVal == INDEFINITE)

   204 		{

   205 			return 0;

   206 		}

   207 		else

   208 		{

   209 			return clampValue(aValue, aNewMaxVal);

   210 		}

   211 	}

   212 

   213 	  /**

   214 	 * Validates the value against the range.

   215 	 *

   216 	 * @param aValue the value.

   217 	 * @param aMaxVal the maximum value.

   218 	 * @return validated value.

   219 	 */

   220     private static int clampValue(int aValue, int aMaxVal)

   221     {

   222         aValue = Math.min(aValue, aMaxVal);

   223         aValue = Math.max(aValue, 0);

   224         return aValue;

   225     }

   226 

   227     /**

   228      * @return if the Gauge is indefinite.

   229      */

   230     boolean isIndefinite()

   231     {

   232         return (maxValue == INDEFINITE);

   233     }

   234 

   235     /* (non-Javadoc)

   236      * @see javax.microedition.lcdui.Item#isFocusable()

   237      */

   238     boolean isFocusable()

   239     {

   240         return (isInteractive() || (getNumCommands() > 0));

   241     }

   242 

   243     /**

   244      * Returns if this indicator meets the restrictions for its use in an Alert.

   245      */

   246     boolean isSuitableForAlert()

   247     {

   248         return (!isInteractive()

   249                 && getParent() == null

   250                 && getLabel() == null

   251                 && getLayout() == Item.LAYOUT_DEFAULT

   252                 && !isSizeLocked()

   253                 && getNumCommands() == 0

   254                 && getItemCommandListener() == null);

   255     }

   256 

   257     /**

   258      * Called by widget listeners to update Item value.

   259      */

   260     void internalSetValue(int newValue)

   261     {

   262         value = validateValue(newValue, maxValue);

   263 		updateParent(UPDATE_VALUE);

   264         // notify item state listener

   265         notifyStateChanged();

   266     }

   267 

   268     /**

   269      * Return layout with optional custom flags.

   270      *

   271      * @return layout directive

   272      */

   273     int internalGetLayout()

   274     {

   275         return super.internalGetLayout() | Item.LAYOUT_NEWLINE_BEFORE;

   276     }

   277 

   278     /**

   279      * Updates Form or Alert.

   280      *

   281      * @see javax.microedition.lcdui.Item#updateParent(int)

   282      */

   283     void updateParent(int updateReason)

   284     {

   285         if(isContainedInAlert())

   286         {

   287             ((Alert) getParent()).updateIndicator();

   288         }

   289         else

   290         {

   291             super.updateParent(updateReason);

   292         }

   293     }

   294 

   295     /**

   296      * Calculates minimum size of this item.

   297      *

   298      * @return Minimum size.

   299      */

   300     Point calculateMinimumSize()

   301     {

   302         return GaugeLayouter.calculateMinimumBounds(this);

   303     }

   304 

   305     /**

   306      * Calculates preferred size of this item.

   307      *

   308      * @return Preferred size.

   309      */

   310     Point calculatePreferredSize()

   311     {

   312         return GaugeLayouter.calculatePreferredBounds(this);

   313     }

   314 

   315 }

   316