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: /**
030: * The <code>TextBox</code> class is a <code>Screen</code> that allows
031: * the user to enter and edit
032: * text.
033: *
034: * <p>A <code>TextBox</code> has a maximum size, which is the maximum
035: * number of characters
036: * that can be stored in the object at any time (its capacity). This limit is
037: * enforced when the <code>TextBox</code> instance is constructed,
038: * when the user is editing text within the <code>TextBox</code>, as well as
039: * when the application program calls methods on the
040: * <code>TextBox</code> that modify its
041: * contents. The maximum size is the maximum stored capacity and is unrelated
042: * to the number of characters that may be displayed at any given time.
043: * The number of characters displayed and their arrangement into rows and
044: * columns are determined by the device. </p>
045: *
046: * <p>The implementation may place a boundary on the maximum size, and the
047: * maximum size actually assigned may be smaller than the application had
048: * requested. The value actually assigned will be reflected in the value
049: * returned by {@link #getMaxSize() getMaxSize()}. A defensively-written
050: * application should compare this value to the maximum size requested and be
051: * prepared to handle cases where they differ.</p>
052: *
053: * <p>The text contained within a <code>TextBox</code> may be more
054: * than can be displayed at
055: * one time. If this is the case, the implementation will let the user scroll
056: * to view and edit any part of the text. This scrolling occurs transparently
057: * to the application. </p>
058: *
059: * <p>If the constraints are set to {@link TextField#ANY}
060: * The text may contain <A HREF="Form.html#linebreak">line breaks</A>.
061: * The display of the text must break accordingly and the user must be
062: * able to enter line break characters. </p>
063: *
064: * <p><code>TextBox</code> has the concept of
065: * <em>input constraints</em> that is identical to
066: * <code>TextField</code>. The <code>constraints</code> parameters of
067: * methods within the
068: * <code>TextBox</code> class use constants defined in the {@link
069: * TextField TextField}
070: * class. See the description of
071: * <a href="TextField.html#constraints">input constraints</a>
072: * in the <code>TextField</code> class for the definition of these
073: * constants. <code>TextBox</code> also has the same notions as
074: * <code>TextField</code> of the <em>actual contents</em> and the
075: * <em>displayed contents</em>, described in the same section.
076: * </p>
077: *
078: * <p><code>TextBox</code> also has the concept of <em>input
079: * modes</em> that is identical
080: * to <code>TextField</code>. See the description of <a
081: * href="TextField.html#modes">input
082: * modes</a> in the <code>TextField</code> class for more details.
083: *
084: * @since MIDP 1.0
085: */
086:
087: public class TextBox extends Screen {
088:
089: /**
090: * Creates a new <code>TextBox</code> object with the given title
091: * string, initial
092: * contents, maximum size in characters, and constraints.
093: * If the text parameter is <code>null</code>, the
094: * <code>TextBox</code> is created empty.
095: * The <code>maxSize</code> parameter must be greater than zero.
096: * An <code>IllegalArgumentException</code> is thrown if the
097: * length of the initial contents string exceeds <code>maxSize</code>.
098: * However,
099: * the implementation may assign a maximum size smaller than the
100: * application had requested. If this occurs, and if the length of the
101: * contents exceeds the newly assigned maximum size, the contents are
102: * truncated from the end in order to fit, and no exception is thrown.
103: *
104: * @param title the title text to be shown with the display
105: * @param text the initial contents of the text editing area,
106: * <code>null</code> may be used to
107: * indicate no initial content
108: * @param maxSize the maximum capacity in characters. The implementation
109: * may limit
110: * boundary maximum capacity and the actually assigned capacity may
111: * me smaller than requested. A defensive application will test the
112: * actually given
113: * capacity with {@link #getMaxSize()}.
114: * @param constraints see <a href="TextField.html#constraints">input
115: * constraints</a>
116: *
117: * @throws IllegalArgumentException if <code>maxSize</code> is zero or less
118: * @throws IllegalArgumentException if the <code>constraints</code>
119: * parameter is invalid
120: * @throws IllegalArgumentException if <code>text</code> is illegal
121: * for the specified constraints
122: * @throws IllegalArgumentException if the length of the string exceeds
123: * the requested maximum capacity
124: */
125: public TextBox(String title, String text, int maxSize,
126: int constraints) {
127: super (title);
128:
129: synchronized (Display.LCDUILock) {
130:
131: textField = new TextField(null, text, maxSize, constraints,
132: true);
133: textField.lSetOwner(this );
134:
135: displayableLF = textBoxLF = LFFactory.getFactory()
136: .getTextBoxFormLF(this );
137: }
138: }
139:
140: /**
141: * Gets the contents of the <code>TextBox</code> as a string value.
142: *
143: * @return the current contents
144: * @see #setString
145: */
146: public String getString() {
147: return textField.getString();
148: }
149:
150: /**
151: * Sets the contents of the <code>TextBox</code> as a string
152: * value, replacing the previous contents.
153: *
154: * @param text the new value of the <code>TextBox</code>, or
155: * <code>null</code> if the <code>TextBox</code> is to
156: * be made empty
157: * @throws IllegalArgumentException if <code>text</code>
158: * is illegal for the current
159: * <a href="TextField.html#constraints">input constraints</a>
160: * @throws IllegalArgumentException if the text would exceed the current
161: * maximum capacity
162: * @see #getString
163: */
164: public void setString(String text) {
165: textField.setString(text);
166: }
167:
168: /**
169: * Copies the contents of the <code>TextBox</code> into a
170: * character array starting at
171: * index zero. Array elements beyond the characters copied are left
172: * unchanged.
173: *
174: * @param data the character array to receive the value
175: * @return the number of characters copied
176: * @throws ArrayIndexOutOfBoundsException if the array is too short for the
177: * contents
178: * @throws NullPointerException if <code>data</code> is <code>null</code>
179: * @see #setChars
180: */
181: public int getChars(char[] data) {
182: return textField.getChars(data);
183: }
184:
185: /**
186: * Sets the contents of the <code>TextBox</code> from a character
187: * array, replacing the
188: * previous contents. Characters are copied from the region of the
189: * <code>data</code> array
190: * starting at array index <code>offset</code> and running for
191: * <code>length</code> characters.
192: * If the data array is <code>null</code>, the <code>TextBox</code>
193: * is set to be empty and the other parameters are ignored.
194: *
195: * <p>The <code>offset</code> and <code>length</code> parameters must
196: * specify a valid range of characters within
197: * the character array <code>data</code>.
198: * The <code>offset</code> parameter must be within the
199: * range <code>[0..(data.length)]</code>, inclusive.
200: * The <code>length</code> parameter
201: * must be a non-negative integer such that
202: * <code>(offset + length) <= data.length</code>.</p>
203: *
204: * @param data the source of the character data
205: * @param offset the beginning of the region of characters to copy
206: * @param length the number of characters to copy
207: * @throws ArrayIndexOutOfBoundsException if <code>offset</code>
208: * and <code>length</code> do not specify
209: * a valid range within the data array
210: * @throws IllegalArgumentException if <code>data</code>
211: * is illegal for the current
212: * <a href="TextField.html#constraints">input constraints</a>
213: * @throws IllegalArgumentException if the text would exceed the current
214: * maximum capacity
215: * @see #getChars
216: */
217: public void setChars(char[] data, int offset, int length) {
218: textField.setChars(data, offset, length);
219: }
220:
221: /**
222: * Inserts a string into the contents of the <code>TextBox</code>.
223: * The string is
224: * inserted just prior to the character indicated by the
225: * <code>position</code> parameter, where zero specifies the first
226: * character of the contents of the <code>TextBox</code>. If
227: * <code>position</code> is
228: * less than or equal to zero, the insertion occurs at the beginning of
229: * the contents, thus effecting a prepend operation. If
230: * <code>position</code> is greater than or equal to the current size of
231: * the contents, the insertion occurs immediately after the end of the
232: * contents, thus effecting an append operation. For example,
233: * <code>text.insert(s, text.size())</code> always appends the string
234: * <code>s</code> to the current contents.
235: *
236: * <p>The current size of the contents is increased by the number of
237: * inserted characters. The resulting string must fit within the current
238: * maximum capacity. </p>
239: *
240: * <p>If the application needs to simulate typing of characters it can
241: * determining the location of the current insertion point
242: * ("caret")
243: * using the with {@link #getCaretPosition() getCaretPosition()} method.
244: * For example,
245: * <code>text.insert(s, text.getCaretPosition())</code> inserts the string
246: * <code>s</code> at the current caret position.</p>
247: *
248: * @param src the <code>String</code> to be inserted
249: * @param position the position at which insertion is to occur
250: *
251: * @throws IllegalArgumentException if the resulting contents
252: * would be illegal for the current
253: * <a href="TextField.html#constraints">input constraints</a>
254: * @throws IllegalArgumentException if the insertion would
255: * exceed the current
256: * maximum capacity
257: * @throws NullPointerException if <code>src</code> is <code>null</code>
258: */
259: public void insert(String src, int position) {
260: textField.insert(src, position);
261: }
262:
263: /**
264: * Inserts a subrange of an array of characters into the contents of
265: * the <code>TextBox</code>. The <code>offset</code> and
266: * <code>length</code> parameters indicate the subrange of
267: * the data array to be used for insertion. Behavior is otherwise
268: * identical to {@link #insert(String, int) insert(String, int)}.
269: *
270: * <p>The <code>offset</code> and <code>length</code> parameters must
271: * specify a valid range of characters within
272: * the character array <code>data</code>.
273: * The <code>offset</code> parameter must be within the
274: * range <code>[0..(data.length)]</code>, inclusive.
275: * The <code>length</code> parameter
276: * must be a non-negative integer such that
277: * <code>(offset + length) <= data.length</code>.</p>
278: *
279: * @param data the source of the character data
280: * @param offset the beginning of the region of characters to copy
281: * @param length the number of characters to copy
282: * @param position the position at which insertion is to occur
283: *
284: * @throws ArrayIndexOutOfBoundsException if <code>offset</code>
285: * and <code>length</code> do not
286: * specify a valid range within the data array
287: * @throws IllegalArgumentException if the resulting contents
288: * would be illegal for the current
289: * <a href="TextField.html#constraints">input constraints</a>
290: * @throws IllegalArgumentException if the insertion would
291: * exceed the current
292: * maximum capacity
293: * @throws NullPointerException if <code>data</code> is <code>null</code>
294: */
295: public void insert(char[] data, int offset, int length, int position) {
296: textField.insert(data, offset, length, position);
297: }
298:
299: /**
300: * Deletes characters from the <code>TextBox</code>.
301: *
302: * <p>The <code>offset</code> and <code>length</code> parameters must
303: * specify a valid range of characters within
304: * the contents of the <code>TextBox</code>.
305: * The <code>offset</code> parameter must be within the
306: * range <code>[0..(size())]</code>, inclusive.
307: * The <code>length</code> parameter
308: * must be a non-negative integer such that
309: * <code>(offset + length) <= size()</code>.</p>
310: *
311: * @param offset the beginning of the region to be deleted
312: * @param length the number of characters to be deleted
313: *
314: * @throws IllegalArgumentException if the resulting contents
315: * would be illegal for the current
316: * <a href="TextField.html#constraints">input constraints</a>
317: * @throws StringIndexOutOfBoundsException if <code>offset</code>
318: * and <code>length</code> do not
319: * specify a valid range within the contents of the <code>TextBox</code>
320: */
321: public void delete(int offset, int length) {
322: textField.delete(offset, length);
323: }
324:
325: /**
326: * Returns the maximum size (number of characters) that can be
327: * stored in this <code>TextBox</code>.
328: * @return the maximum size in characters
329: * @see #setMaxSize
330: */
331: public int getMaxSize() {
332: return textField.getMaxSize();
333: }
334:
335: /**
336: * Sets the maximum size (number of characters) that can be
337: * contained in this
338: * <code>TextBox</code>. If the current contents of the
339: * <code>TextBox</code> are larger than
340: * <code>maxSize</code>, the contents are truncated to fit.
341: *
342: * @param maxSize the new maximum size
343: *
344: * @return assigned maximum capacity - may be smaller than requested.
345: * @throws IllegalArgumentException if <code>maxSize</code> is zero or less.
346: * @throws IllegalArgumentException if the contents
347: * after truncation would be illegal for the current
348: * <a href="TextField.html#constraints">input constraints</a>
349: * @see #getMaxSize
350: */
351: public int setMaxSize(int maxSize) {
352: return textField.setMaxSize(maxSize);
353: }
354:
355: /**
356: * Gets the number of characters that are currently stored in this
357: * <code>TextBox</code>.
358: * @return the number of characters
359: */
360: public int size() {
361: // returns a value relative to the display text including formatting
362: return textField.size();
363: }
364:
365: /**
366: * Gets the current input position. For some UIs this may block and ask
367: * the user for the intended caret position, and on other UIs this may
368: * simply return the current caret position.
369: *
370: * @return the current caret position, <code>0</code> if at the beginning
371: */
372: public int getCaretPosition() {
373: // returns a value relative to the flat input text
374: return textField.getCaretPosition();
375: }
376:
377: /**
378: * Sets the input constraints of the <code>TextBox</code>. If the
379: * current contents
380: * of the <code>TextBox</code> do not match the new constraints,
381: * the contents are
382: * set to empty.
383: *
384: * @param constraints see
385: * <a href="TextField.html#constraints">input constraints</a>
386: *
387: * @throws IllegalArgumentException if the value of the constraints
388: * parameter is invalid
389: * @see #getConstraints
390: */
391: public void setConstraints(int constraints) {
392: textField.setConstraints(constraints);
393: }
394:
395: /**
396: * Gets the current input constraints of the <code>TextBox</code>.
397: *
398: * @return the current constraints value (see
399: * <a href="TextField.html#constraints">input constraints</a>)
400: * @see #setConstraints
401: */
402: public int getConstraints() {
403: return textField.getConstraints();
404: }
405:
406: /**
407: * Sets a hint to the implementation as to the input mode that should be
408: * used when the user initiates editing of this
409: * <code>TextBox</code>. The
410: * <code>characterSubset</code> parameter names a subset of Unicode
411: * characters that is used by the implementation to choose an initial
412: * input mode. If <code>null</code> is passed, the implementation should
413: * choose a default input mode.
414: *
415: * <p>See <a href="TextField#modes">Input Modes</a> for a full
416: * explanation of input modes. </p>
417: *
418: * @param characterSubset a string naming a Unicode character subset,
419: * or <code>null</code>
420: *
421: */
422: public void setInitialInputMode(String characterSubset) {
423: textField.setInitialInputMode(characterSubset);
424: }
425:
426: /*
427: * package private
428: */
429:
430: /** text field object to put on the form */
431: TextField textField;
432:
433: /** Look & feel object associated with this TextBox */
434: FormLF textBoxLF;
435:
436: } // class TextBox
|