001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.lcdui;
028:
029: import com.sun.midp.lcdui.CommandAccess;
030:
031: /**
032: * The <code>Command</code> class is a construct that encapsulates
033: * the semantic information of an action. The behavior that the command
034: * activates is not encapsulated in this object. This means that command
035: * contains
036: * only information about "command" not the actual action
037: * that happens when
038: * command
039: * is activated. The action is defined in a
040: * {@link CommandListener CommandListener}
041: * associated
042: * with the <code>Displayable</code>. <code>Command</code> objects are
043: * <em>presented</em>
044: * in the user interface and the way they are presented
045: * may depend on the semantic information contained within the command.
046: *
047: * <P><code>Commands</code> may be implemented in any user interface
048: * construct that has
049: * semantics for activating a single action. This, for example, can be a soft
050: * button, item in a menu, or some other direct user interface construct.
051: * For example, a
052: * speech interface may present these commands as voice tags. </P>
053: *
054: * <P>The mapping to concrete user interface constructs may also depend on the
055: * total number of the commands.
056: * For example, if an application asks for more abstract commands than can
057: * be mapped onto
058: * the available physical buttons on a device, then the device may use an
059: * alternate human interface such as a menu. For example, the abstract
060: * commands that
061: * cannot be mapped onto physical buttons are placed in a menu and the label
062: * "Menu" is mapped onto one of the programmable buttons. </P>
063: *
064: * <p>A command contains four pieces of information: a <em>short label</em>,
065: * an optional <em>long label</em>, a
066: * <em>type</em>, and a <em>priority</em>.
067: * One of the labels is used for the visual
068: * representation of the command, whereas the type and the priority indicate
069: * the semantics of the command. </p>
070: *
071: * <a name="label"></a>
072: * <h3>Labels</h3>
073: *
074: * <p> Each command includes one or two label strings. The label strings are
075: * what the application requests to be shown to the user to represent this
076: * command. For example, one of these strings may appear next to a soft button
077: * on the device or as an element in a menu. For command types other than
078: * <code>SCREEN</code>, the labels provided may be overridden by a
079: * system-specific label
080: * that is more appropriate for this command on this device. The contents of
081: * the label strings are otherwise not interpreted by the implementation. </p>
082: *
083: * <p>All commands have a short label. The long label is optional. If the
084: * long label is not present on a command, the short label is always used.
085: * </p>
086: *
087: * <p>The short label string should be as short as possible so that it
088: * consumes a minimum of screen real estate. The long label can be longer and
089: * more descriptive, but it should be no longer than a few words. For
090: * example, a command's short label might be "Play", and its
091: * long label
092: * might be "Play Sound Clip".</p>
093: *
094: * <p>The implementation chooses one of the labels to be presented in the user
095: * interface based on the context and the amount of space available. For
096: * example, the implementation might use the short label if the command
097: * appears on a soft button, and it might use the long label if the command
098: * appears on a menu, but only if there is room on the menu for the long
099: * label. The implementation may use the short labels of some commands and
100: * the long labels of other commands, and it is allowed to switch between
101: * using the short and long label at will. The application cannot determine
102: * which label is being used at any given time. </p>
103: *
104: * <a name="type"></a>
105: * <h3>Type</h3>
106: *
107: * <p> The application uses the command
108: * type to specify the intent of this command. For example, if the
109: * application specifies that the command is of type
110: * <code>BACK</code>, and if the device
111: * has a standard of placing the "back" operation on a
112: * certain soft-button,
113: * the implementation can follow the style of the device by using the semantic
114: * information as a guide. The defined types are
115: * {@link #BACK BACK},
116: * {@link #CANCEL CANCEL},
117: * {@link #EXIT EXIT},
118: * {@link #HELP HELP},
119: * {@link #ITEM ITEM},
120: * {@link #OK OK},
121: * {@link #SCREEN SCREEN},
122: * and
123: * {@link #STOP STOP}. </p>
124: *
125: * <a name="priority"></a>
126: * <h3>Priority</h3>
127: *
128: * <p> The application uses the priority
129: * value to describe the importance of this command relative to other commands
130: * on the same screen. Priority values are integers, where a lower number
131: * indicates greater importance. The actual values are chosen by the
132: * application. A priority value of one might indicate the most important
133: * command, priority values of two, three, four, and so on indicate commands
134: * of lesser importance. </p>
135: *
136: * <p>Typically,
137: * the implementation first chooses the placement of a command based on
138: * the type of command and then places similar commands based on a priority
139: * order. This could mean that the command with the highest priority is
140: * placed so that user can trigger it directly and that commands with lower
141: * priority are placed on a menu. It is not an error for there to be commands
142: * on the same screen with the same priorities and types. If this occurs, the
143: * implementation will choose the order in which they are presented. </p>
144: *
145: * <p>For example, if the application has the following set of commands: </P>
146: * <TABLE BORDER="2">
147: * <TR>
148: * <TD ROWSPAN="1" COLSPAN="1">
149: * <pre><code>
150: * new Command("Buy", Command.ITEM, 1);
151: * new Command("Info", Command.ITEM, 1);
152: * new Command("Back", Command.BACK, 1); </code></pre>
153: * </TD>
154: * </TR>
155: * </TABLE>
156: * <P>
157: * An implementation with two soft buttons may map the
158: * <code>BACK</code> command to
159: * the right
160: * soft button and create an "Options" menu on the left soft
161: * button to contain
162: * the other commands.<BR>
163: * <IMG SRC="doc-files/command1.gif" width=190 height=268><BR>
164: * When user presses the left soft button, a menu with the two remaining
165: * <code>Commands</code> appears:<BR>
166: * <IMG SRC="doc-files/command2.gif" width=189 height=260><BR>
167: * If the application had three soft buttons, all commands can be mapped
168: * to soft buttons:
169: * <BR><IMG SRC="doc-files/command3.gif" width=189 height=261></P>
170: *
171: * <p>The application is always responsible for providing the means for the
172: * user to progress through different screens. An application may set up a
173: * screen that has no commands. This is allowed by the API but is generally
174: * not useful; if this occurs the user would have no means to move to another
175: * screen. Such program would simply considered to be in error. A typical
176: * device should provide a means for the user to direct the application manager
177: * to kill the erroneous application.
178: * @since MIDP 1.0
179: */
180:
181: public class Command {
182:
183: // public members //
184:
185: /**
186: * Specifies an application-defined command that pertains to the current
187: * screen. Examples could be "Load" and
188: * "Save". A <code>SCREEN</code> command
189: * generally applies to the entire screen's contents or to navigation
190: * among screens. This is in contrast to the <CODE>ITEM</CODE> type,
191: * which applies to the currently activated or focused item or element
192: * contained within this screen.
193: *
194: * <P>Value <code>1</code> is assigned to <code>SCREEN</code>.</P>
195: */
196: public static final int SCREEN = 1;
197:
198: /**
199: * A navigation command that returns the user to the logically
200: * previous screen.
201: * The jump to the previous screen is not done automatically by the
202: * implementation
203: * but by the {@link CommandListener#commandAction commandAction}
204: * provided by
205: * the application.
206: * Note that the application defines the actual action since the strictly
207: * previous screen may not be logically correct.
208: *
209: * <P>Value <code>2</code> is assigned to <code>BACK</code>.</P>
210: *
211: * @see #CANCEL
212: * @see #STOP
213: */
214: public static final int BACK = 2;
215:
216: /**
217: * A command that is a standard negative answer to a dialog implemented by
218: * current screen.
219: * Nothing is cancelled automatically by the implementation; cancellation
220: * is implemented
221: * by the {@link CommandListener#commandAction commandAction} provided by
222: * the application.
223: *
224: * <p> With this command type, the application hints to the implementation
225: * that the user wants to dismiss the current screen without taking any
226: * action
227: * on anything that has been entered into the current screen, and usually
228: * that
229: * the user wants to return to the prior screen. In many cases
230: * <code>CANCEL</code> is
231: * interchangeable with <code>BACK</code>, but <code>BACK</code>
232: * is mainly used for navigation
233: * as in a browser-oriented applications. </p>
234: *
235: * <P>Value <code>3</code> is assigned to <code>CANCEL</code>.</P>
236: *
237: * @see #BACK
238: * @see #STOP
239: */
240: public static final int CANCEL = 3;
241:
242: /**
243: * A command that is a standard positive answer to a dialog implemented by
244: * current screen.
245: * Nothing is done automatically by the implementation; any action taken
246: * is implemented
247: * by the {@link CommandListener#commandAction commandAction} provided by
248: * the application.
249: *
250: * <p> With this command type the application hints to the
251: * implementation that
252: * the user will use this command to ask the application to confirm
253: * the data
254: * that has been entered in the current screen and to proceed to the next
255: * logical screen. </p>
256: *
257: * <P><code>CANCEL</code> is often used together with <code>OK</code>.</P>
258: *
259: * <P>Value <code>4</code> is assigned to <code>OK</code>.</P>
260: *
261: * @see #CANCEL
262: */
263: public static final int OK = 4;
264:
265: /**
266: * This command specifies a request for on-line help.
267: * No help information is shown automatically by the implementation.
268: * The
269: * {@link CommandListener#commandAction commandAction} provided by the
270: * application is responsible for showing the help information.
271: *
272: * <P>Value <code>5</code> is assigned to <code>HELP</code>.</P>
273: */
274: public static final int HELP = 5;
275:
276: /**
277: * A command that will stop some currently running
278: * process, operation, etc.
279: * Nothing is stopped automatically by the implementation.
280: * The cessation must
281: * be performed
282: * by the {@link CommandListener#commandAction commandAction} provided by
283: * the application.
284: *
285: * <p> With this command type the application hints to the
286: * implementation that
287: * the user will use this command to stop any currently running process
288: * visible to the user on the current screen. Examples of running processes
289: * might include downloading or sending of data. Use of the
290: * <code>STOP</code>
291: * command does
292: * not necessarily imply a switch to another screen. </p>
293: *
294: * <P>Value <code>6</code> is assigned to <code>STOP</code>.</P>
295: *
296: * @see #BACK
297: * @see #CANCEL
298: */
299: public static final int STOP = 6;
300:
301: /**
302: * A command used for exiting from the application. When the user
303: * invokes this command, the implementation does not exit automatically.
304: * The application's
305: * {@link CommandListener#commandAction commandAction}
306: * will be called, and it should exit the application if it
307: * is appropriate to do so.
308: *
309: * <P>Value <code>7</code> is assigned to <code>EXIT</code>.</P>
310: */
311: public static final int EXIT = 7;
312:
313: /**
314: * With this command type the application can hint to the
315: * implementation that the command is specific to the items of
316: * the <code>Screen</code> or the elements of a
317: * <code>Choice</code>. Normally this
318: * means that command relates to the focused item or element.
319: * For example, an implementation of <code>List</code> can use
320: * this information for
321: * creating context sensitive menus.
322: *
323: * <P>Value <code>8</code> is assigned to <code>ITEM</code>.</P>
324: */
325: public static final int ITEM = 8;
326:
327: // protected members //
328:
329: /**
330: * The label rendered on the screen for this Command.
331: * Chosen from the available set of labels.
332: */
333: String shortLabel;
334: /**
335: * The long Label for this Command
336: */
337: String longLabel;
338: /**
339: * The type of this Command
340: */
341: int commandType;
342: /**
343: * The priority of this Command
344: */
345: int priority;
346:
347: // private members //
348:
349: /**
350: * This is a private id that is set when adding a command to
351: * a Displayable,
352: * such that the Command may be easily identified at a later
353: * date only by its id
354: */
355: private int id;
356:
357: // Constructors //
358:
359: /**
360: * Creates a new command object with the given short
361: *
362: * <a href="#label">label</a>,
363: * <a href="#type">type</a>, and
364: * <a href="#priority">priority</a>.
365: *
366: * The newly created command has no long label. This constructor is
367: * identical to <code>Command(label, null, commandType, priority)</code>.
368: *
369: * @param label the command's short label
370: * @param commandType the command's type
371: * @param inp_priority the command's priority value
372: *
373: * @throws NullPointerException if label is <code>null</code>
374: * @throws IllegalArgumentException if the <code>commandType</code>
375: * is an invalid type
376: *
377: * @see #Command(String, String, int, int)
378: */
379: public Command(String label, int commandType, int inp_priority) {
380: this (label, null, commandType, inp_priority);
381: }
382:
383: /**
384: * Creates a new command object with the given
385: * <a href="#label">labels</a>,
386: * <a href="#type">type</a>, and
387: * <a href="#priority">priority</a>.
388: *
389: * <p>The short label is required and must not be
390: * <code>null</code>. The long label is
391: * optional and may be <code>null</code> if the command is to have
392: * no long label.</p>
393: *
394: * @param shortLabel the command's short label
395: * @param longLabel the command's long label, or <code>null</code> if none
396: * @param commandType the command's type
397: * @param inp_priority the command's priority value
398: *
399: * @throws NullPointerException if <code>shortLabel</code> is
400: * <code>null</code>
401: * @throws IllegalArgumentException if the <code>commandType</code> is an
402: * invalid type
403: *
404: */
405: public Command(String shortLabel, String longLabel,
406: int commandType, int inp_priority) {
407: initialize(commandType, inp_priority);
408: setLabel(shortLabel, longLabel);
409: }
410:
411: // public method implementations //
412:
413: /**
414: * Gets the short label of the command.
415: *
416: * @return the <code>Command's</code> short label
417: */
418: public String getLabel() {
419: // SYNC NOTE: return of atomic value, no locking necessary
420: return shortLabel;
421: }
422:
423: /**
424: * Gets the long label of the command.
425: *
426: * @return the <code>Command's</code> long label, or
427: * <code>null</code> if the <code>Command</code> has no long
428: * label
429: *
430: */
431: public String getLongLabel() {
432: // SYNC NOTE: return of atomic value, no locking necessary
433: return longLabel;
434: }
435:
436: /**
437: * Gets the type of the command.
438: *
439: * @return type of the <code>Command</code>
440: */
441: public int getCommandType() {
442: // SYNC NOTE: return of atomic value, no locking necessary
443: return commandType;
444: }
445:
446: /**
447: * Gets the priority of the command.
448: *
449: * @return priority of the <code>Command</code>
450: */
451: public int getPriority() {
452: // SYNC NOTE: return of atomic value, no locking necessary
453: return priority;
454: }
455:
456: // protected method implementations //
457:
458: /**
459: * Get the internal ID of this Command
460: *
461: * @return int The integer id associated with this specific Command
462: */
463: int getID() {
464: return id;
465: }
466:
467: // package private method implementations //
468:
469: /**
470: * Sets the internal id used to uniquely identify
471: * this command.
472: * This method is intended to be called from Displayable
473: * addCommand()
474: *
475: * @param num the int to set this id to
476: */
477: void setInternalID(int num) {
478: this .id = num;
479: }
480:
481: // private method implementations //
482:
483: /**
484: * Sets the label of the command. If the label is null
485: * throw NullPointerException.
486: * @param shortLabel the short Label string
487: * @param longLabel the long Label string
488: */
489: private void setLabel(String shortLabel, String longLabel) {
490:
491: if (shortLabel == null) {
492: throw new NullPointerException();
493: }
494: this .shortLabel = shortLabel;
495: this .longLabel = longLabel;
496: }
497:
498: /**
499: * This method will initialize this Command object is only called
500: * by its constructors.
501: *
502: * @param commandType The command's <a href="#type">type</a>, one of
503: * {@link #BACK BACK},
504: * {@link #CANCEL CANCEL},
505: * {@link #EXIT EXIT},
506: * {@link #HELP HELP},
507: * {@link #ITEM ITEM},
508: * {@link #OK OK},
509: * {@link #SCREEN SCREEN},
510: * or
511: * {@link #STOP STOP}
512: *
513: * @param inp_priority The command's <a href="#priority">priority</a>
514: * value
515: *
516: * @throws IllegalArgumentException if the commandType is an invalid
517: * type
518: * @throws NullPointerException if label is null, or if any one of
519: * the array of labels is null
520: */
521: private final void initialize(int commandType, int inp_priority) {
522:
523: if ((commandType < SCREEN) || (commandType > ITEM)) {
524: throw new IllegalArgumentException();
525: }
526:
527: this .commandType = commandType;
528: priority = inp_priority;
529: }
530:
531: } // class Command
|