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     private int maxValue;

    52     private int value;

    53     private boolean interactive;

    54 

    55     /**

    56      * Constructor.

    57      *

    58      * @param name the label.

    59      * @param interactive if its interactive.

    60      * @param maxVal the maximum value.

    61      * @param initVal the initial value.

    62      */

    63     public Gauge(String name, boolean interactive, int maxVal, int initVal) {

    64         setLabel(name);

    65         this.interactive = interactive;

    66         setMaxValue(maxVal);

    67         setValue(initVal);

    68     }

    69 

    70     /**

    71      * Check value validity.

    72      *

    73      * @param value the value.

    74      * @param maxVal the maximum value.

    75      * @return validated value.

    76      */

    77     private static int checkValue(int value, int maxVal) {

    78         if (maxVal == INDEFINITE) {

    79             switch (value) {

    80                 case CONTINUOUS_IDLE:

    81                 case INCREMENTAL_IDLE:

    82                 case CONTINUOUS_RUNNING:

    83                 case INCREMENTAL_UPDATING:

    84                     break;

    85                 default:

    86                     throw new IllegalArgumentException(

    87                             MsgRepository.GAUGE_EXCEPTION_INVALID_VALUE);

    88             }

    89             return value;

    90         }

    91         else {

    92             // make sure the value is in [0, maxValue] range

    93             value = (value < 0 ? 0 : value);

    94             value = (value > maxVal ? maxVal : value);

    95             return value;

    96         }

    97     }

    98 

    99     /**

   100      * Check maximum value validity.

   101      *

   102      * @param maxVal the maximum value.

   103      * @param interactive is interactive.

   104      * @return validated maximum value.

   105      */

   106     private static int checkMaxValue(int maxVal, boolean interactive) {

   107         if (!interactive) {

   108             if (maxVal == INDEFINITE) {

   109                 return maxVal;

   110             }

   111         }

   112         if (maxVal <= 0) {

   113             throw new IllegalArgumentException(

   114                     MsgRepository.GAUGE_EXCEPTION_INVALID_MAXVALUE);

   115         }

   116         return maxVal;

   117     }

   118 

   119     /**

   120      * Sets value of this gauge.

   121      *

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

   123      */

   124     public void setValue(int value) {

   125         // TODO: eSWT support required

   126         /*

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

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

   129          * that requires eSWT extension.

   130          */

   131         this.value = checkValue(value, this.maxValue);

   132         updateParent(UPDATE_CONTENT);

   133     }

   134 

   135     /**

   136      * Get value.

   137      *

   138      * @return the value.

   139      */

   140     public int getValue() {

   141         return value;

   142     }

   143 

   144     /**

   145      * Set the maximum value.

   146      *

   147      * @param maxValue the maximum value.

   148      */

   149     public void setMaxValue(int maxValue) {

   150         this.maxValue = checkMaxValue(maxValue, interactive);

   151         this.value = checkValue(getValue(), this.maxValue);

   152         updateParent(UPDATE_CONTENT);

   153     }

   154 

   155     /**

   156      * Get maximum value.

   157      *

   158      * @return the maximum value.

   159      */

   160     public int getMaxValue() {

   161         return maxValue;

   162     }

   163 

   164     /**

   165      * Checks if gauge is interactive.

   166      *

   167      * @return true if the Gauge is interactive.

   168      */

   169     public boolean isInteractive() {

   170         return interactive;

   171     }

   172 

   173     /**

   174      * Updates Form or Alert.

   175      *

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

   177      */

   178     void updateParent(int updateReason) {

   179         if (isContainedInAlert()) {

   180             ((Alert) getParent()).updateIndicator();

   181         }

   182         else {

   183             super.updateParent(updateReason);

   184         }

   185     }

   186 

   187     /**

   188      * Calculates minimum size of this item.

   189      *

   190      * @return Minimum size.

   191      */

   192     Point calculateMinimumSize() {

   193         return GaugeLayouter.calculateMinimumBounds(this);

   194     }

   195 

   196     /**

   197      * Calculates preferred size of this item.

   198      *

   199      * @return Preferred size.

   200      */

   201     Point calculatePreferredSize() {

   202         return GaugeLayouter.calculatePreferredBounds(this);

   203     }

   204 

   205     /**

   206      * Called by widget listeners to update Item value.

   207      */

   208     void internalSetValue(int newValue) {

   209         this.value = checkValue(newValue, this.maxValue);

   210         // notify item state listener

   211         notifyStateChanged();

   212     }

   213 

   214     /**

   215      * Return layout with optional custom flags.

   216      *

   217      * @return layout directive

   218      */

   219     int internalGetLayout() {

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

   221     }

   222 

   223     /**

   224      * @return if the Gauge is indefinite.

   225      */

   226     boolean isIndefinite() {

   227         return (maxValue == INDEFINITE);

   228     }

   229 

   230     /**

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

   232      */

   233     boolean isSuitableForAlert() {

   234         return (!isInteractive()

   235                 && getParent() == null

   236                 && !hasLabel()

   237                 && getLayout() == Item.LAYOUT_DEFAULT

   238                 && !isSizeLocked()

   239                 && getNumCommands() == 0

   240                 && getItemCommandListener() == null);

   241     }

   242 

   243     /* (non-Javadoc)

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

   245      */

   246     boolean isFocusable() {

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

   248     }

   249 

   250 }