001: /*=============================================================================
002: * Copyright Texas Instruments, Inc., 2002. All Rights Reserved.
003: *
004: * This program is free software; you can redistribute it and/or modify
005: * it under the terms of the GNU General Public License as published by
006: * the Free Software Foundation; either version 2 of the License, or
007: * (at your option) any later version.
008: *
009: * This program is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012: * GNU General Public License for more details.
013: *
014: * You should have received a copy of the GNU General Public License
015: * along with this program; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: */
018:
019: package ti.chimera.service;
020:
021: /**
022: * The "prompt" service, used to implement a mechanism to display info/warning/
023: * error messages to the user, or prompt the user for input. The purpose is
024: * to seperate the decision of how to interact with user from code that needs
025: * to interact with the user. This service could be implemented, for example,
026: * either by poping up dialogs, or with console I/O... it is even possible that
027: * an "expect"-like implementation of this service could be used to automate
028: * things.
029: *
030: * @author Rob Clark
031: * @version 0.1
032: */
033: public abstract class Prompt extends ti.chimera.Service {
034: /**
035: * Class Constructor.
036: */
037: public Prompt() {
038: super ("prompt");
039: }
040:
041: /**
042: * Display an error message to the user. This method blocks until the user
043: * dismisses the message.
044: *
045: * @param msg the error message to display
046: */
047: public abstract void showErrorMessage(String msg);
048:
049: /**
050: * Display a warning message to the user. This method blocks until the user
051: * dismisses the message.
052: *
053: * @param msg the warning message to display
054: */
055: public abstract void showWarningMessage(String msg);
056:
057: /**
058: * Display an info message to the user. This method blocks until the user
059: * dismisses the message.
060: *
061: * @param msg the info message to display
062: */
063: public abstract void showInfoMessage(String msg);
064:
065: /**
066: * Display a progress message to the user. A progress message has a progress
067: * bar to display progress. This returns a {@link Progress} to allow the
068: * client code to programatically update the progress, and dispose of the
069: * progress message once complete.
070: * <p>
071: * The progress displayed to the user is initially in "indeterminate" mode
072: * to indicate that the length of time to take is unknown. Once the length
073: * of time is known, {@link Progress#setRange} and {@link Progress#setValue}
074: * can be used to update the progress display.
075: * <p>
076: * For example:
077: * <pre>
078: * var progress = services["prompt"].showProgress("This will take a while");
079: *
080: * // progress is in "indeterminate" mode until you compute length of time:
081: * progress.setRange( 0, computeTime() );
082: *
083: * var t = currentTimeMillis();
084: * while( !done() )
085: * {
086: * doSomeWork();
087: * p.setValue( currentTimeMillis() - t );
088: * }
089: *
090: * // done, so dismiss progress dialog:
091: * progress.dispose();
092: * </pre>
093: *
094: * @param msg the message to display
095: * @return an object allowing the progress display to be programatically
096: * updated by the client code
097: */
098: public abstract Progress showProgress(String msg);
099:
100: /**
101: * An object implementing this interface is returned by {@link #showProgress}
102: * in order to allow the client code to programatically update or dismiss
103: * the progress.
104: */
105: public interface Progress {
106: /**
107: * Update the range of this display. The value (see {@link #setValue})
108: * must be between <code>min</code> and <code>max</code> inclusive.
109: *
110: * @param min the min
111: * @param max the max
112: */
113: public void setRange(int min, int max);
114:
115: /**
116: * Update the progress. The <code>val</code> should be between the
117: * min and max (inclusive) specified in {@link #setRange}. It is
118: * an error to call this if {@link #setRange} has not been called.
119: *
120: * @param val the new value
121: */
122: public void setValue(int val);
123:
124: /**
125: * Get the current progress value.
126: *
127: * @return the current value
128: */
129: public int getValue();
130:
131: /**
132: * Indicate that the progress has completed, and the progress dialog or
133: * message should no longer be displayed.
134: */
135: public void dispose();
136: }
137:
138: /**
139: * Ask a question of the user. The <code>msg</code> is displayed to the
140: * user, who must then choose one of the choices. The choice selected
141: * by the user is returned. This method blocks until a result is choisen.
142: * For example:
143: * <pre>
144: * var result = services["prompt"].askQuestion( "Do you want to continue?", [ "Yes", "No" ] );
145: * if( result == "No" )
146: * return;
147: * ....
148: * </pre>
149: *
150: * @param msg the message to display
151: * @param choices array of choices presented to the user
152: * @return one of the elements from <code>choices</code>
153: */
154: public abstract String askQuestion(String msg, String[] choices);
155: }
156:
157: /*
158: * Local Variables:
159: * tab-width: 2
160: * indent-tabs-mode: nil
161: * mode: java
162: * c-indentation-style: java
163: * c-basic-offset: 2
164: * eval: (c-set-offset 'substatement-open '0)
165: * End:
166: */
|