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 java.util.Vector;

    20 

    21 import javax.microedition.lcdui.EventDispatcher.LCDUIEvent;

    22 

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

    24 

    25 /**

    26  * Abstract class representing an item.<br>

    27  */

    28 public abstract class Item {

    29 

    30     /**

    31      * A layout directive.

    32      */

    33     public static final int LAYOUT_DEFAULT = 0;

    34 

    35     /**

    36      * A layout directive.

    37      */

    38     public static final int LAYOUT_LEFT = 1;

    39 

    40     /**

    41      * A layout directive.

    42      */

    43     public static final int LAYOUT_RIGHT = 2;

    44 

    45     /**

    46      * A layout directive.

    47      */

    48     public static final int LAYOUT_CENTER = 3;

    49 

    50     /**

    51      * A layout directive.

    52      */

    53     public static final int LAYOUT_TOP = 16;

    54 

    55     /**

    56      * A layout directive.

    57      */

    58     public static final int LAYOUT_BOTTOM = 32;

    59 

    60     /**

    61      * A layout directive.

    62      */

    63     public static final int LAYOUT_VCENTER = 48;

    64 

    65     /**

    66      * A layout directive.

    67      */

    68     public static final int LAYOUT_NEWLINE_BEFORE = 256;

    69 

    70     /**

    71      * A layout directive.

    72      */

    73     public static final int LAYOUT_NEWLINE_AFTER = 512;

    74 

    75     /**

    76      * A layout directive.

    77      */

    78     public static final int LAYOUT_SHRINK = 1024;

    79 

    80     /**

    81      * A layout directive.

    82      */

    83     public static final int LAYOUT_EXPAND = 2048;

    84 

    85     /**

    86      * A layout directive.

    87      */

    88     public static final int LAYOUT_VSHRINK = 4096;

    89 

    90     /**

    91      * A layout directive.

    92      */

    93     public static final int LAYOUT_VEXPAND = 8192;

    94 

    95     /**

    96      * A layout directive indicating that MIDP 2 layout rules are used.

    97      */

    98     public static final int LAYOUT_2 = 16384;

    99 

   100     /**

   101      * An appearance mode value.

   102      */

   103     public static final int PLAIN = 0;

   104 

   105     /**

   106      * An appearance mode value.

   107      */

   108     public static final int HYPERLINK = 1;

   109 

   110     /**

   111      * An appearance mode value.

   112      */

   113     public static final int BUTTON = 2;

   114 

   115     /**

   116      * Combination of all possible layout directives.

   117      */

   118     private static final int LAYOUT_BITMASK =

   119           LAYOUT_DEFAULT

   120         | LAYOUT_LEFT

   121         | LAYOUT_RIGHT

   122         | LAYOUT_CENTER

   123         | LAYOUT_TOP

   124         | LAYOUT_BOTTOM

   125         | LAYOUT_VCENTER

   126         | LAYOUT_NEWLINE_BEFORE

   127         | LAYOUT_NEWLINE_AFTER

   128         | LAYOUT_SHRINK

   129         | LAYOUT_EXPAND

   130         | LAYOUT_VSHRINK

   131         | LAYOUT_VEXPAND

   132         | LAYOUT_2;

   133 

   134     static final int LAYOUT_HORIZONTAL_MASK = LAYOUT_CENTER; // 15;

   135 

   136     static final int LAYOUT_VERTICAL_MASK = LAYOUT_VCENTER; // 48;

   137 

   138 

   139     static final int UPDATE_NONE = 0;

   140 

   141     static final int UPDATE_ADDCOMMAND = 1;

   142 

   143     static final int UPDATE_REMOVECOMMAND = 2;

   144 

   145     /**

   146      * Item content has changed. Re-layouting not needed.

   147      */

   148     static final int UPDATE_CONTENT = 3; // general update value

   149 

   150     static final int UPDATE_REASON_MASK = 255;

   151 

   152     /**

   153      * Item height has changed. Re-layouting not needed.

   154      */

   155     static final int UPDATE_HEIGHT_CHANGED = 256;

   156 

   157     /**

   158      * Item width is changed. Re-layouting asap.

   159      */

   160     static final int UPDATE_WIDTH_CHANGED = 512;

   161 

   162     /**

   163      * Item width and height changed. Re-layouting asap.

   164      */

   165     static final int UPDATE_SIZE_CHANGED =

   166         UPDATE_HEIGHT_CHANGED | UPDATE_WIDTH_CHANGED;

   167 

   168     private String label;

   169 

   170     /**

   171      * Vector of commands added to this item that have eSWT Command associated

   172      * with them.

   173      */

   174     private Vector commands = new Vector();

   175     private ItemCommandListener itemCommandListener;

   176 

   177     private Command defaultCommand;

   178     private Screen parent;

   179 

   180     private int layout;

   181     private int lockedPrefWidth = -1;

   182     private int lockedPrefHeight = -1;

   183 

   184     private Point calculatedMinSize;

   185     private Point calculatedPrefSize;

   186 

   187     private boolean focused;

   188     private boolean visible;

   189 

   190     /**

   191      * Sets the parent of this Item.

   192      * @param parent new Parent. If null, current parent is removed.

   193      */

   194     void setParent(Screen parent) {

   195         this.parent = parent;

   196     }

   197 

   198     /**

   199      * Gets the Item's parent.

   200      *

   201      * @return the Item's parent or null if it has none.

   202      */

   203     Screen getParent() {

   204         return parent;

   205     }

   206 

   207     /**

   208      * Sets the label of the item.

   209      *

   210      * @param newLabel New label to be set.

   211      * @throws IllegalStateException If this item is contained within an alert.

   212      */

   213     public void setLabel(String newLabel) {

   214         if (isContainedInAlert()) {

   215             throw new IllegalStateException(

   216                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   217         }

   218         label = newLabel;

   219         updateParent(UPDATE_SIZE_CHANGED);

   220     }

   221 

   222     /**

   223      * Gets the label of the item.

   224      *

   225      * @return The label of the item.

   226      */

   227     public String getLabel() {

   228         return label;

   229     }

   230 

   231     /**

   232      * Returns if this item has a valid label, not null and not empty.

   233      */

   234     boolean hasLabel() {

   235         return ((label != null) && (!label.equals("")));

   236     }

   237 

   238     /**

   239      * Gets item's current layout.

   240      *

   241      * @return A combination of layout directives currently in use.

   242      */

   243     public int getLayout() {

   244         return layout;

   245     }

   246 

   247     /**

   248      * Sets the layout of the item.

   249      *

   250      * @param newLayout a Combination of layout directives to be used.

   251      * @throws IllegalArgumentException if newLayout is not valid bitwise OR

   252      *             combination of layout directives spesified in this class.

   253      * @throws IllegalStateException If this Item is contained within an Alert.

   254      */

   255     public void setLayout(int newLayout) {

   256         if (isContainedInAlert()) {

   257             throw new IllegalStateException(

   258                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   259         }

   260 

   261         if (!isValidLayout(newLayout)) {

   262             throw new IllegalArgumentException(

   263                     MsgRepository.ITEM_EXCEPTION_INVALID_LAYOUT);

   264         }

   265         layout = newLayout;

   266         Logger.method(this, "setLayout", String.valueOf(layout));

   267         updateParent(UPDATE_SIZE_CHANGED);

   268     }

   269 

   270     /**

   271      * Adds command to this item. If same command is already added to this item,

   272      * nothing happens.

   273      *

   274      * @param command A command to be added.

   275      * @throws NullPointerException if cmd is null.

   276      * @throws IllegalStateException If this Item is contained within an Alert.

   277      */

   278     public void addCommand(Command command) {

   279         if (isContainedInAlert()) {

   280             throw new IllegalStateException(

   281                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   282         }

   283         if (command == null) {

   284             throw new NullPointerException(

   285                     MsgRepository.ITEM_EXCEPTION_NULL_COMMAND_ADDED);

   286         }

   287         if (!commands.contains(command)) {

   288             commands.addElement(command);

   289 

   290             int reason = UPDATE_ADDCOMMAND;

   291 

   292             if (this instanceof StringItem && commands.size() == 1) {

   293                 reason |= UPDATE_SIZE_CHANGED;

   294             }

   295             if (this instanceof ImageItem && commands.size() == 1) {

   296                 reason |= UPDATE_SIZE_CHANGED;

   297             }

   298 

   299             updateParent(reason, command);

   300         }

   301     }

   302 

   303     /**

   304      * Removes command from the item. If command doesn't exists in this item,

   305      * nothing happens.

   306      *

   307      * @param command The command to be removed.

   308      */

   309     public void removeCommand(Command command) {

   310         // It is not specified what should happen when this method is

   311         // called with null-parameter !

   312         if (command != null && commands.contains(command)) {

   313             // Remove command from commands-vector

   314             commands.removeElement(command);

   315 

   316             int reason = UPDATE_REMOVECOMMAND;

   317 

   318             if (this instanceof StringItem && commands.size() == 0) {

   319                 reason |= UPDATE_SIZE_CHANGED;

   320             }

   321             if (this instanceof ImageItem && commands.size() == 0) {

   322                 reason |= UPDATE_SIZE_CHANGED;

   323             }

   324 

   325             updateParent(reason, command);

   326         }

   327     }

   328 

   329 

   330     /**

   331      * Sets Listener which will receive command events associated with this

   332      * item.

   333      *

   334      * @param newItemCmdListener A new listener. If null, already existing

   335      *            listener is removed.

   336      * @throws IllegalStateException If this Item is contained within an Alert.

   337      */

   338     public void setItemCommandListener(ItemCommandListener newItemCmdListener) {

   339         if (isContainedInAlert()) {

   340             throw new IllegalStateException(

   341                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   342         }

   343         itemCommandListener = newItemCmdListener;

   344     }

   345 

   346     /**

   347      * Gets the minimum width of this item.

   348      *

   349      * @return Minimum width.

   350      */

   351     public int getMinimumWidth() {

   352         return getCalculatedMinimumSize().x;

   353     }

   354 

   355     /**

   356      * Gets the minimum height of this item.

   357      *

   358      * @return Minimum height.

   359      */

   360     public int getMinimumHeight() {

   361         return getCalculatedMinimumSize().y;

   362     }

   363 

   364     private Point getCalculatedMinimumSize() {

   365         if (calculatedMinSize == null) {

   366             calculatedMinSize = calculateMinimumSize();

   367             // Logger.method(this, "calculateMinimumSize", calculatedMinSize);

   368         }

   369         return calculatedMinSize;

   370     }

   371 

   372     /**

   373      * Calculates minimum size of this item.

   374      *

   375      * @return Minimum size.

   376      */

   377     abstract Point calculateMinimumSize();

   378 

   379     /**

   380      * Gets the preferred width of this item.

   381      *

   382      * @return Preferred width.

   383      */

   384     public int getPreferredWidth() {

   385         if (lockedPrefWidth >= 0) {

   386             if (calculatedMinSize == null) {

   387                 checkLockedSizes();

   388             }

   389             return lockedPrefWidth;

   390         }

   391         else {

   392             return getCalculatedPreferredSize().x;

   393         }

   394     }

   395 

   396     /**

   397      * Gets the preferred height of this item.

   398      *

   399      * @return Preferred height.

   400      */

   401     public int getPreferredHeight() {

   402         if (lockedPrefHeight >= 0) {

   403             if (calculatedMinSize == null) {

   404                 checkLockedSizes();

   405             }

   406             return lockedPrefHeight;

   407         }

   408         else {

   409             return getCalculatedPreferredSize().y;

   410         }

   411     }

   412 

   413     private Point getCalculatedPreferredSize() {

   414         if (calculatedPrefSize == null) {

   415             calculatedPrefSize = calculatePreferredSize();

   416             // Logger.method(this, "calculatePreferredSize", calculatedPrefSize);

   417         }

   418         return calculatedPrefSize;

   419     }

   420 

   421     void checkLockedSizes() {

   422         if (lockedPrefWidth >= 0) {

   423             lockedPrefWidth = Math.min(

   424                     Math.max(lockedPrefWidth, getMinimumWidth()),

   425                     ItemLayouter.getMaximumItemWidth(null));

   426         }

   427         if (lockedPrefHeight >= 0) {

   428             lockedPrefHeight = Math.max(lockedPrefHeight, getMinimumHeight());

   429         }

   430     }

   431 

   432     /**

   433      * Invalidates this Item's calculated preferred size. Forces the

   434      * implementation to calculate it again.

   435      */

   436     void invalidateCachedSizes() {

   437         calculatedMinSize = null;

   438         calculatedPrefSize = null;

   439     }

   440 

   441     /**

   442      * Calculates preferred size of this item.

   443      *

   444      * @return Preferred size.

   445      */

   446     abstract Point calculatePreferredSize();

   447 

   448     /**

   449      * Sets the preferred size of this item. If new value is larger than -1 and

   450      * less than minimum value, the minimum value is used instead. If value is

   451      * larger than minimum value, the dimension is locked to provided value. It

   452      * is possible to unlock dimension by setting value to -1.

   453      *

   454      * @param w New preferred width.

   455      * @param h New preferred height.

   456      * @throws IllegalArgumentException if w or h is less than -1.

   457      * @throws IllegalStateException If this Item is contained within an Alert.

   458      */

   459     public synchronized void setPreferredSize(int w, int h) {

   460         if (isContainedInAlert()) {

   461             throw new IllegalStateException(

   462                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   463         }

   464         if ((w < -1) || (h < -1)) {

   465             throw new IllegalArgumentException(

   466                     MsgRepository.ITEM_EXCEPTION_INVALID_DIMENSION);

   467         }

   468 

   469         lockedPrefWidth = w;

   470         lockedPrefHeight = h;

   471         checkLockedSizes();

   472         Logger.method(this, "setPrefSize",

   473                 String.valueOf(lockedPrefWidth),

   474                 String.valueOf(lockedPrefHeight));

   475         updateParent(UPDATE_SIZE_CHANGED);

   476     }

   477 

   478     /**

   479      * Sets the default command of this item. This method doesn't remove

   480      * commands from the item, it just tells which command is the default one.

   481      *

   482      * @param cmd New default command. If cmd doesn't exists in this item yet it

   483      *            is added to it. Null means that this item wont have default

   484      *            command at all after this call.

   485      * @throws IllegalStateException If this Item is contained within an Alert.

   486      */

   487     public void setDefaultCommand(Command cmd) {

   488         if (isContainedInAlert()) {

   489             throw new IllegalStateException(

   490                     MsgRepository.ITEM_EXCEPTION_OWNED_BY_ALERT);

   491         }

   492         defaultCommand = cmd;

   493         if (cmd != null) {

   494             // It is safe to call addCommand() even if command already exists

   495             // because the addCommand() wont create duplicates:

   496             addCommand(cmd);

   497         }

   498 

   499         // Form need to be updated if this item is focused:

   500         updateParent(UPDATE_SIZE_CHANGED);

   501     }

   502 

   503     /**

   504      * Makes this item's containing form to notify item's ItemStateListener.

   505      * This method must be called only when item's state has actually changed

   506      * and when that change has occured because of user.

   507      *

   508      * If ItemStateListener is not set to the Form where this Item belongs,

   509      * nothing happens.

   510      *

   511      * @throws IllegalStateException If the item is not owned by a form.

   512      */

   513     public void notifyStateChanged() {

   514         if (!isContainedInForm()) {

   515             throw new IllegalStateException(

   516                     MsgRepository.ITEM_EXCEPTION_NOT_OWNED_BY_FORM);

   517         }

   518         // Notify item state listener

   519         ((Form) parent).notifyItemStateChanged(this);

   520     }

   521 

   522     /**

   523      * Is this item's size locked.

   524      */

   525     boolean isSizeLocked() {

   526         return (lockedPrefWidth >= 0) || (lockedPrefHeight >= 0);

   527     }

   528 

   529     /**

   530      * Gets locked preferred width of this item.

   531      *

   532      * @return Locked preferred width. If width is not locked, returns -1.

   533      */

   534     int getLockedPreferredWidth() {

   535         return lockedPrefWidth;

   536     }

   537 

   538     /**

   539      * Gets locked preferred height of this item.

   540      *

   541      * @return Locked preferred height. If height is not locked, returns -1.

   542      */

   543     int getLockedPreferredHeight() {

   544         return lockedPrefHeight;

   545     }

   546 

   547     /**

   548      * Gets LAYOUT_2 width of this item.

   549      */

   550     int getLayoutWidth() {

   551         if (hasLayout(LAYOUT_SHRINK)) {

   552             return getMinimumWidth();

   553         }

   554         return getPreferredWidth();

   555     }

   556 

   557     /**

   558      * Gets LAYOUT_2 height of this item.

   559      */

   560     int getLayoutHeight() {

   561         if (hasLayout(LAYOUT_VSHRINK)) {

   562             return getMinimumHeight();

   563         }

   564         return getPreferredHeight();

   565     }

   566 

   567     /**

   568      * If the item is owned by an Alert.

   569      */

   570     boolean isContainedInAlert() {

   571         return (parent != null && parent instanceof Alert);

   572     }

   573 

   574     /**

   575      * If the item is owned by an Form.

   576      */

   577     boolean isContainedInForm() {

   578         return (parent != null && parent instanceof Form);

   579     }

   580 

   581     /**

   582      * Return internal layout with optional custom flags.

   583      *

   584      * @return layout directive

   585      */

   586     int internalGetLayout() {

   587         return getLayout();

   588     }

   589 

   590     /**

   591      * Updates the parent if it's a Form.

   592      */

   593     void updateParent(int updateReason) {

   594         updateParent(updateReason, null);

   595     }

   596 

   597     /**

   598      * Updates the parent if it's a Form.

   599      *

   600      * @param param additional parameter

   601      */

   602     void updateParent(int updateReason, Object param) {

   603         if ((updateReason & UPDATE_SIZE_CHANGED) != 0) {

   604             invalidateCachedSizes();

   605         }

   606         if (isContainedInForm()) {

   607             ((Form) parent).updateItemState(this, updateReason, param);

   608         }

   609     }

   610 

   611     boolean hasLayout(int aLayout) {

   612         return (getLayout() & aLayout) != 0;

   613     }

   614 

   615     /**

   616      * Check that new layout is bitwise OR combination of layout

   617      * directives:

   618      *

   619      * @param layout Layout combination to be check.

   620      * @return true If provided layout is valid.

   621      */

   622     static boolean isValidLayout(int layout) {

   623         if ((layout & (0xffffffff ^ LAYOUT_BITMASK)) != 0) {

   624             return false;

   625         }

   626         return true;

   627     }

   628 

   629     /**

   630      * Get Item horizontal layout directive: LAYOUT_LEFT, LAYOUT_RIGHT,

   631      * LAYOUT_CENTER, DEFAULT_LAYOUT .

   632      *

   633      * @param layout item Layout.

   634      * @return horizontal layout of an Item.

   635      */

   636     static int getHorizontalLayout(int layout) {

   637         return layout & Item.LAYOUT_HORIZONTAL_MASK;

   638     }

   639 

   640     /**

   641      * Get Item vertical Layout directive: LAYOUT_TOP, LAYOUT_BOTTOM,

   642      * LAYOUT_VCENTER.

   643      *

   644      * @param layout item Layout.

   645      * @return vertical layout of an Item.

   646      */

   647     static int getVerticalLayout(int layout) {

   648         return layout & Item.LAYOUT_VERTICAL_MASK;

   649     }

   650 

   651     /**

   652      * Is item focusable.

   653      */

   654     boolean isFocusable() {

   655         return false;

   656     }

   657 

   658     /**

   659      * Sets current item as focused

   660      */

   661     void internalSetFocused(boolean isFocused) {

   662         if (isFocusable()) {

   663             focused = isFocused;

   664         }

   665     }

   666 

   667     /**

   668      * Check that item has current focus on it.

   669      *

   670      * @return true if item has focus.

   671      */

   672     boolean isFocused() {

   673         return focused;

   674     }

   675 

   676     /**

   677      * Sets current item visibility

   678      */

   679     void internalSetVisible(boolean isVisible) {

   680         this.visible = isVisible;

   681     }

   682 

   683     /**

   684      * Check that item is visible.

   685      *

   686      * @return true if item is visible

   687      */

   688     boolean isVisible() {

   689         return visible;

   690     }

   691 

   692     /**

   693      * Returns the number of commands.

   694      *

   695      * @return number of commands.

   696      */

   697     int getNumCommands() {

   698         return commands.size();

   699     }

   700 

   701     /**

   702      * Gets default command of this item.

   703      *

   704      * @return Default command or null if no default set.

   705      */

   706     Command getDefaultCommand() {

   707         return defaultCommand;

   708     }

   709 

   710     /**

   711      * Returns the Default Command or if not set, then the first Command.

   712      */

   713     Command getMSKCommand() {

   714         Command ret = null;

   715         if (defaultCommand != null) {

   716             ret = defaultCommand;

   717         }

   718         else if (commands.elementAt(0) != null) {

   719             ret = (Command) commands.elementAt(0);

   720         }

   721         return ret;

   722     }

   723 

   724     /**

   725      * Calls the command action on the owning Items command listener.

   726      *

   727      * @param command the Command

   728      */

   729     void callCommandAction(Command command) {

   730         if (itemCommandListener != null && command != null) {

   731         	EventDispatcher eventDispatcher = EventDispatcher.instance();

   732         	LCDUIEvent event = eventDispatcher.newEvent(

   733         			LCDUIEvent.ITEM_COMMANDACTION, 

   734         			this);

   735         	event.command = command;

   736         	event.itemCommandListener = itemCommandListener;

   737         	eventDispatcher.postEvent(event);

   738         }

   739     }

   740 

   741     /**

   742      * Gets commands of this item.

   743      *

   744      * @return Vector of commands added to this item.

   745      *      Vector may be empty but not null.

   746      */

   747     Vector getCommands() {

   748         return commands;

   749     }

   750 

   751     /**

   752      * Gets ItemCommandListener.

   753      * @return Current ItemCommandListener or null if

   754      *      no listener set.

   755      */

   756     ItemCommandListener getItemCommandListener() {

   757         return itemCommandListener;

   758     }

   759 

   760     /*

   761      * Dispatcher thread calls. 

   762      */

   763     void doCallback(LCDUIEvent event) {

   764     	switch(event.type) {

   765     	case LCDUIEvent.ITEM_COMMANDACTION:

   766     		event.itemCommandListener.commandAction(event.command, this);

   767     		break;

   768     	}

   769     }

   770 }