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: * Implements a "ticker-tape", a piece of text that runs
031: * continuously across the display. The direction and speed of scrolling are
032: * determined by the implementation. While animating, the ticker string
033: * scrolls continuously. That is, when the string finishes scrolling off the
034: * display, the ticker starts over at the beginning of the string.
035: *
036: * <p> There is no API provided for starting and stopping the ticker. The
037: * application model is that the ticker is always scrolling continuously.
038: * However, the implementation is allowed to pause the scrolling for power
039: * consumption purposes, for example, if the user doesn't interact with the
040: * device for a certain period of time. The implementation should resume
041: * scrolling the ticker when the user interacts with the device again. </p>
042: *
043: * <p>The text of the ticker may contain
044: * <A HREF="Form.html#linebreak">line breaks</A>.
045: * The complete text MUST be displayed in the ticker;
046: * line break characters should not be displayed but may be used
047: * as separators. </p>
048: *
049: * <p> The same ticker may be shared by several <code>Displayable</code>
050: * objects ("screens"). This can be accomplished by calling
051: * {@link Displayable#setTicker setTicker()} on each of them.
052: * Typical usage is for an application to place the same ticker on
053: * all of its screens. When the application switches between two screens that
054: * have the same ticker, a desirable effect is for the ticker to be displayed
055: * at the same location on the display and to continue scrolling its contents
056: * at the same position. This gives the illusion of the ticker being attached
057: * to the display instead of to each screen. </p>
058: *
059: * <p> An alternative usage model is for the application to use different
060: * tickers on different sets of screens or even a different one on each
061: * screen. The ticker is an attribute of the <code>Displayable</code> class
062: * so that
063: * applications may implement this model without having to update the ticker
064: * to be displayed as the user switches among screens. </p>
065: * @since MIDP 1.0
066: */
067:
068: public class Ticker {
069:
070: /**
071: * Constructs a new <code>Ticker</code> object, given its initial
072: * contents string.
073: * @param str string to be set for the <code>Ticker</code>
074: * @throws NullPointerException if <code>str</code> is <code>null</code>
075: */
076: public Ticker(String str) {
077:
078: if (str == null) {
079: throw new NullPointerException();
080: }
081:
082: synchronized (Display.LCDUILock) {
083: message = str;
084: displayedMessage = str.trim().replace('\n', ' ');
085: tickerLF = LFFactory.getFactory().getTickerLF(this );
086: }
087: }
088:
089: /**
090: * Sets the string to be displayed by this ticker. If this ticker is active
091: * and is on the display, it immediately begins showing the new string.
092: * @param str string to be set for the <code>Ticker</code>
093: * @throws NullPointerException if <code>str</code> is <code>null</code>
094: * @see #getString
095: */
096: public void setString(String str) {
097:
098: if (str == null) {
099: throw new NullPointerException();
100: }
101:
102: if (str.equals(message)) {
103: return;
104: }
105:
106: synchronized (Display.LCDUILock) {
107: // Save the original unmodified message so that getString()
108: // returns that.
109: message = str;
110:
111: // According to the spec, linebreak characters should
112: // not be displayed in the ticker and could be used as
113: // separators. We will use a single white space as the
114: // separator.
115:
116: displayedMessage = str.trim().replace('\n', ' ');
117: tickerLF.lSetString(displayedMessage);
118: }
119: }
120:
121: /**
122: * Gets the string currently being scrolled by the ticker.
123: * @return string of the ticker
124: * @see #setString
125: */
126: public String getString() {
127: // SYNC NOTE: return of atomic value, no locking necessary
128: return message;
129: }
130:
131: /** The message set in this Ticker */
132: private String message;
133:
134: /**
135: * The message being displayed in this Ticker. #getString() will
136: * only return what is stored in "message" and not in "displayedMessage",
137: * which is only used for display purposes.
138: */
139: String displayedMessage;
140:
141: /** Look and Feel corresponding to this Ticker */
142: TickerLF tickerLF;
143: }
|