public class Display
extends java.lang.Object
Display
class provides an application with access to the
device's user interface hardware resources. It includes static methods for
obtaining Display
objects as well as instance methods to retrieve
their properties and display text on them.
A device MAY have one or more display resources for interacting with the
user. Each resource includes a line-oriented display device and may also include
keys or other appropriate means for user input. Those means MUST create key
events, that can be processed by a Dssplay via an associated
KeyListener
, as defined in the kavax.microedition.key
package.
An application gains access to a display resource using a Display
object. Each Display
object represents a specific application's
use of a specific resource, rather than the resource itself. Hence, for a
given display resource, each application has its own dedicated
Display
object for accessing it.
Multiple applications may want to use the same display resource simultaneously. A line-oriented display resource is exclusive in nature; that is, it can be made available to only one application at a time. For example, regular key events are typically provided to a single application.
The nature of specific resources and the policies for sharing them between
applications are largely platform dependent. However, the Display
class defines two states that should be used in conjunction with the platform's
policies for sharing display resources.
When a Display
has assigned
status, it is assigned to the corresponding display resource. The
resource is available to this Display
then. For a given display
resource, there can be no more than one assigned Display
. If the
resource is also used by the native UI of the device, there may be times when
no Display
is assigned.
When a Display
has unassigned
status, all of its display resources are relinquished and unavailable
to the application. For a given set of display resources, there can be any
number of Display
s that are in the unassigned state. A
Display
is initially in this state and it cannot be changed unless
text is shown on it.
Display
becomes assigned or
unassigned by calling the Display
's
setDisplayState
method. However, these requests to change the state are not guaranteed and are
subject to the device's application display sharing management behavior.
The underlying hardware resource represented by a Display
may
not always be available. For example, some resources are dynamic and their
availability may be temporary in nature.
Therefore, a Display
object has a hardware state to indicate the
state of its underlying resource. This state refers to the display resource
itself, rather than a specific application's ability to use it. Thus, all
Display
s that refer to the same hardware have the same hardware
state, regardless of which application they belong to.
The hardware life-cycle is defined with three states:
ENABLED
- The Display
's hardware is active and potentially available for
use by the application. Attempts to use the Display
should be
successful, but due to the asynchronous nature of the API and possible system
use, immediate availability of the resource is not guaranteed. DISABLED
- The Display
's hardware is inactive and currently cannot be used
to interact with the user. When a display resource is disabled, all of the
corresponding Display
s are temporarily placed in the UNASSIGNED
state. When the hardware is enabled again, the Display
state
should be restored to the most recent ASSIGNED/UNASSIGNED request made; if no
requests were made while the hardware was disabled, then the restored state
should simply be the Display
's state immediately before the
hardware became disabled. ABSENT
- This state only applies to an Auxiliary display hardware resource and it
indicates that the resource is no longer accessible by the device. Attempts
to use an absent display will result in an exception being thrown.
Display
s that represent absent hardware are automatically placed
in the unassigned
state.
Applications should not retain references to absent Display
s
since they cannot be re-used. If the same Auxiliary display hardware becomes
accessible once more, a new Display
object is created to access
it.
For every application, there is always one primary Display
object. The primary Display
corresponds to the device's main
display that is normally used to access its features. The application can get
a reference to the primary Display
instance by calling the
getDisplay()
method. The application may call the
getDisplay()
method at any time during course of its execution.
The Display
object returned by all calls to getDisplay()
will remain the same during this time.
In addition to the primary Display
, one or more secondary
Display
s may also be available to an application. These
Display
s may also include auxiliary display devices that are
available to the device via a suitable connection.
The getDisplays(MIDlet, boolean)
method returns a list of
Display
objects corresponding to a given application. The primary
Display
object, if being part of the result list, is always
returned as the first element in the list, followed by any secondary
Display
objects that are also available.
A Display
may or may not be able to process key events (depending
on whether the associated hardware is coupled with a user input facility like
a keyboard).
Besides a line-oriented display may support several text colors, or just a single color. Display can also support backlight with a fixed color or the capability to change backlight color as well. A display may be also capable to scroll texts vertically or horizontally or both. If a display is capable to scroll text horizontally and/or vertically, the scrolling mode can be switched on and off, independend for both scrolling directions (if both are supported).
If a display provides capabilities for both, horizontal and vertical scrolling, it is strongly recommended to use only one of those possibilities at a time for the sake of readability of the display.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
BACKLIGHT
To be used as an event name for
Event . |
static int |
BACKLIGHT_DIM
Valid value for
BACKLIGHT events. |
static int |
BACKLIGHT_OFF
Valid value for
BACKLIGHT events. |
static int |
BACKLIGHT_ON
Valid value for
BACKLIGHT events. |
static DisplayColor |
BACKLIGHT_STANDARD_COLOR
Standard backlight color for this
Display . |
static int |
MODE_ACTIVE
Activity mode indicating that power-saving actions should be deferred for as long
as possible to maximize the user's visibility of the display content.
|
static int |
MODE_NORMAL
Activity mode indicating that normal power management behavior should be applied.
|
static DisplayColor |
TEXT_STANDARD_COLOR
Standard text color for this
Display . |
Modifier and Type | Method and Description |
---|---|
DisplayColor |
getBacklightColor()
Retrieves the currently valid backlight color of the display.
|
int |
getCharacterNumberPerLine()
Gets the number of characters to be shown in a single line of the display.
|
int |
getChars(char[] data)
Copies the contents shown in the display into a character array starting
at index zero.
|
int |
getChars(int lineNumber,
char[] data)
Copies the contents shown in the specified line of the display into a
character array starting at index zero.
|
DisplayColor |
getCurrentTextColor()
Retrieves the currently valid text color of the display.
|
static Display |
getDisplay(MIDlet m)
Gets the primary
Display object that is unique to this
application. |
java.lang.String |
getDisplayId()
Retrieves an implementation-specific Id for this
Display . |
static Display[] |
getDisplays(MIDlet m,
boolean keyEventSupport)
Gets a list of all the
Display s for this application. |
DisplayState |
getDisplayState()
Gets the state of this
Display with respect to access to the
underlying hardware. |
DisplayHardwareState |
getHardwareState()
Gets the state of the hardware for this display.
|
int |
getHorizontalScrollingInterval(int lineNumber)
Retrieves horizontal scrolling interval for the specified line of this
display in milliseconds between character shifts.
|
int |
getNumberOfLines()
Gets the number of lines for the display.
|
java.lang.String |
getText()
Retrieves the text currently shown in the display.
|
java.lang.String |
getText(int lineNumber)
Retrieves the text currently shown in a particular line of the display.
|
int |
getVerticalScrollingInterval()
Retrieves vertical scrolling interval for this display in milliseconds
between line shifts.
|
boolean |
isBacklightColorsSupported()
Gets information about backlight color support by the display.
|
boolean |
isBuiltIn()
Checks if this display's hardware is Built-In or Auxiliary.
|
boolean |
isHorizontalScrollingEnabled(int lineNumber)
Retrieves whether horizontal scrolling is enabled for the specified line
number of the display or not.
|
boolean |
isHorizontalScrollingSupported()
Gets information about horizontal scrolling support by the display.
|
boolean |
isKeyEventsSupported()
Indicates whether the display supports key events.
|
boolean |
isTextColorsSupported()
Gets information about text color support by the display.
|
boolean |
isVerticalScrollingEnabled()
Retrieves whether vertical scrolling is enabled for the display or not.
|
boolean |
isVerticalScrollingSupported()
Gets information about vertical scrolling support by the display.
|
DisplayColor |
setBacklightColor(DisplayColor color)
Sets the backlight color to be used by the display from now on.
|
void |
setChars(char[] data,
int offset,
int length)
Sets the text shown by the display from a character array,
replacing the previous text.
|
void |
setChars(char[] data,
int offset,
int length,
boolean blinking,
boolean inverseColor)
This method has the same functionality as
setChars(data, offset, length) , but with the additional possibility
to determine whether the text should be displayed blinking and/or
inversed. |
void |
setChars(int lineNumber,
char[] data,
int offset,
int length)
Sets the text shown by the specified line of the display from a character
array, replacing the previous text of that line.
|
void |
setChars(int lineNumber,
char[] data,
int offset,
int length,
boolean blinking,
boolean inverseColor)
This method has the same functionality as
setChars(lineNumber, data, offset, length) , but with the additional possibility
to determine whether the text should be displayed blinking and/or
inversed. |
DisplayColor |
setCurrentTextColor(DisplayColor color)
Sets the text color to be used on the display from now on.
|
void |
setDisplayListener(DisplayListener l)
Sets a display listener for display events to this
Display ,
replacing any previous DisplayListener . |
void |
setDisplayState(DisplayState state)
Allows the application to request that a
Display becomes
assigned or unassigned. |
void |
setHorizontalScrolling(int lineNumber,
boolean scrollEnable)
Enables or disables horizontal scrolling for the specified line of the
display if it is supported by the underlying hardware.
|
void |
setHorizontalScrollingInterval(int lineNumber,
int interval)
Sets the horizontal scrolling interval for the specified line of this
display in milliseconds between character shifts.
|
void |
setKeyListener(KeyListener listener)
|
void |
setText(int lineNumber,
java.lang.String text)
Sets the text of the specified line of the display as a string value,
replacing the previous contents.
|
void |
setText(int lineNumber,
java.lang.String text,
boolean blinking,
boolean inverseColor)
This method has the same functionality as
setText(lineNumber, text) , but with the additional possibility to
determine whether the text should be displayed blinking and/or inversed. |
void |
setText(java.lang.String text)
Sets the text of the display as a string value, replacing the previous
contents.
|
void |
setText(java.lang.String text,
boolean blinking,
boolean inverseColor)
This method has the same functionality as
setText(text) , but with the additional possibility to determine whether
the text should be displayed blinking and/or inversed. |
void |
setVerticalScrolling(boolean scrollEnable)
Enables or disables vertical scrolling for the display if it is supported
by the underlying hardware.
|
void |
setVerticalScrollingInterval(int interval)
Sets the vertical scrolling interval for this display in milliseconds
between line shifts.
|
public static final java.lang.String BACKLIGHT
Event
.
Indicates the backlight illumination level.
The value SHOULD NOT be changed due to any programmatic
flashing of the backlight through any other API.
The value is an integer with values:
BACKLIGHT_ON
, BACKLIGHT_OFF
, or
BACKLIGHT_DIM
.public static final int BACKLIGHT_OFF
BACKLIGHT
events.
Indicates the backlight is off.BACKLIGHT
,
Constant Field Valuespublic static final int BACKLIGHT_ON
BACKLIGHT
events.
Indicates the backlight is on.BACKLIGHT
,
Constant Field Valuespublic static final int BACKLIGHT_DIM
BACKLIGHT
events.
Indicates the backlight is dim. Any illumination level other
than fully on or off MUST be reported as dim.BACKLIGHT
,
Constant Field Valuespublic static DisplayColor TEXT_STANDARD_COLOR
Display
.
If the display supports more than one text color, the value is implementation
dependent, but it is assumed that this is the color for "normal"
text.public static DisplayColor BACKLIGHT_STANDARD_COLOR
Display
.
If the display does not support backlight, the value has no particular
meaning.
If the display supports more than one backlight color, the value is
implementation dependent.public static final int MODE_NORMAL
Value 0
is assigned to MODE_NORMAL
.
public static final int MODE_ACTIVE
Value 1
is assigned to MODE_ACTIVE
.
public static Display getDisplay(MIDlet m)
Display
object that is unique to this
application.m
- applicationjava.lang.NullPointerException
- if m
is null
public static Display[] getDisplays(MIDlet m, boolean keyEventSupport)
Display
s for this application. If the
passed parameter is false
, the returned array will be at
least one element long; the first element (index 0) contains a
reference to the primary Display
which can also be obtained
using getDisplay(javax.microedition.midlet.MIDlet)
.
The developer can use the parameter to filter the list of
Display
s to only those that support key events. If
false
is used, all Displays are returned regardless of their
ability to support key events. If the Primary Display is part of the list,
it is always returned as the first element.
If the passed parameter is true
, only Display
s
supporting key events will be returned.
The hardware state of the returned Display
s should be
enabled
or
disabled
.
Auxiliary Display
s that have become absent should not be
returned in the list; however, a Display
may become absent
at any time and so the state of a returned Display
object
cannot be guaranteed.
m
- applicationkeyEventSupport
- true
if only Display
s supporting key
events should be listed, false
to list all
Display
sDisplay
s. Containing at least 1 element
if keyEventSupport
parameter is false
,
can also be empty otherwisepublic void setDisplayListener(DisplayListener l)
Display
,
replacing any previous DisplayListener
. A null
reference is allowed and has the effect of removing any existing listener.l
- the new listener, or null
to remove a listener.public void setKeyListener(KeyListener listener)
KeyListener
for key events to this Display
,
replacing any previous KeyListener
. A null
reference is allowed and has the effect of removing any existing listener.listener
- the new listener, or null
to remove a listener.public boolean isTextColorsSupported()
true
if the display supports more than one color,
false
otherwisepublic boolean isVerticalScrollingSupported()
true
if the display supports vertical scrolling,
false
otherwisepublic boolean isHorizontalScrollingSupported()
true
if the display supports horizontal scrolling,
false
otherwisepublic DisplayColor getCurrentTextColor()
isTextColorsSupported()
returns false
, the
return value is always the value of TEXT_STANDARD_COLOR
.
Please notice, that this method always returns the actual
currently valid text color, which has not necessarily to be the one
that was the argument to a previously processed call to setCurrentTextColor
as implementations of that method are assumed to
choose the one of the available colors being closest to the argument
value in case freely configurable colors are not supported.
public DisplayColor setCurrentTextColor(DisplayColor color)
setText(java.lang.String)
that affects the
entire display will cause the entire display written with text in the
newly set color, while a call to setText(int, java.lang.String)
will only affect the specified line to be written in the newly set color,
while other lines' color remains unaffected.
Without a call to this method, the current text color is always
TEXT_STANDARD_COLOR
.
If the display supports freely configurable colors as defined by the RGB model, it is assumed that the text after this call is written in the configured color. If the display only supports a limited number of text colors, implementations are assumed to choose the one of the available colors being closest to the configured value.
If the display does not support test colors, i.e. if a call to
isTextColorsSupported()
returns false
, a call to
this method has no effect and TEXT_STANDARD_COLOR
is returned.
color
- the new text color for the displaypublic boolean isVerticalScrollingEnabled()
isVerticalScrollingSupported()
returns false
, this method
will always return false
.true
if vertical scrolling is enabled,
false
otherwisepublic boolean isHorizontalScrollingEnabled(int lineNumber)
isHorizontalScrollingSupported()
returns false
, this method
will always return false
.lineNumber
- the line number the horizontal scrolling status is
retrieved for, must be between zero (for the first line) and
getNumberOfLines() - 1
(for the last line)true
if horizontal scrolling is enabled for this line,
false
otherwisepublic void setVerticalScrolling(boolean scrollEnable)
isVerticalScrollingSupported()
returns
false
, a call to this method is ignored.scrollEnable
- true
to enable vertical scrolling,
false
to disable vertical scrollingpublic void setHorizontalScrolling(int lineNumber, boolean scrollEnable)
isHorizontalScrollingSupported()
returns false
, a call to this method is ignored.lineNumber
- the line number of the display the horizontal scrolling
should be enabled or disabled for; must be between zero (for the
first line) and getNumberOfLines() - 1
(for the last line)scrollEnable
- true
to enable horizontal scrolling,
false
to disable horizontal scrollingpublic DisplayHardwareState getHardwareState()
ENABLED
,
DISABLED
, or
ABSENT
(applicable to Auxiliary display hardware only).public DisplayState getDisplayState()
Display
with respect to access to the
underlying hardware. The state can be
assigned
, or
unassigned
.Display
public void setDisplayState(DisplayState state)
Display
becomes
assigned or unassigned. However, a requests to change the
Display
state is not guaranteed and subject to the device's
application display sharing management behavior.state
- must be one of assigned
, or unassigned
public boolean isKeyEventsSupported()
true
if this display supports key events,
false
otherwisepublic boolean isBuiltIn()
absent
if the connection to it is lost.true
if the Display
is for Built-In
display hardware, false
if it is for Auxiliary
display hardwarepublic int getCharacterNumberPerLine()
public int getNumberOfLines()
public java.lang.String getText()
In case the display is able to scroll vertically and vertical scrolling mode is set active, the returned text string may contain more than what is visible on the display in a certain moment, e.g. the moment of the call to this method.
setText(java.lang.String)
public java.lang.String getText(int lineNumber) throws java.lang.ArrayIndexOutOfBoundsException
ArrayIndexOutOfBoundsException
is thrown.
In case the display is able to scroll horizontally and horizontal scrolling mode is set active, the returned text string may contain more than what is visible on the display line in a certain moment, e.g. the moment of the call to this method.
In case the display is able to scroll vertically and vertical scrolling mode is set active, the returned text string changes in time, dependend which line of the vertically scrolling text is in the position specified by the lineNumber argument at the point in time the method is called!
lineNumber
- the line number the text should be retrieved for, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)java.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display hassetText(java.lang.String)
public void setText(java.lang.String text)
getText
method will not in all
cases return the text string that was the argument to setText
.
Horizontal scrolling is disabled for any line by a call to this method, not depending on how the horizontal scrolling mode has been before for any display line.
For displaying of the new text, the whole display is used, means the complete former content of the Display (if any) is removed. If the number of characters that can be shown in one line is exceeded, the text continues in the next line (if any). No carriage returns (CRs) are inserted into the text in order to wrap text to the next line. Instead the implementation is encouraged to develop it's own strategy to arrange text on several lines (if available). Where the text is wrapped is implemntation dependent, the implementation is not forced to use all characters of a line and wrap the text exactly at the end of the line. Depending on requirements of readability, the text could be wrapped e.g. where white characters like space or tab appear in the text string.
If the argument string contains carrige returns (CRs), the behavior how these are handled is implementation dependent: Implementations are free to ignore CRs (means: replace them by simple spaces) or start indeed a new text line.
A possible way of implementation could be to internally "translate" a call
to setText(String text)
into an appropriate number of calls
to setText(int lineNumber, String text)
.
text
- the new text to be displayed on the display, or
null
if the display should not show any textgetText()
public void setText(java.lang.String text, boolean blinking, boolean inverseColor)
setText(text)
, but with the additional possibility to determine whether
the text should be displayed blinking and/or inversed.text
- the new text to be displayed on the display, or
null
if the display should not show any textblinking
- true
if text to be displayed should blink,
false
otherwise; if the physical display does
not offer this feature, this parameter is ignoredinverseColor
- true
if text to be displayed should be
shown inversed, means signs in backlight color on background
in text color; false
otherwise; if the physical
display does not offer this feature, this parameter is ignoredsetText(java.lang.String)
public void setText(int lineNumber, java.lang.String text) throws java.lang.ArrayIndexOutOfBoundsException
getText(int linenumber)
method will not in all
cases return the text string that was the argument to this method.
If the argument text string contains carriage returns (CRs), they MUST be ignored, means replaced by simple spaces.
If vertical scrolling is active, the line being in the position of the specified line number at the point of time the method is called is replaced. It is strongly recommended to deactivate scrolling before calling this method though!
lineNumber
- the line number the text should be written to, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)text
- the new text to be displayed in the specified line of the
display, or null
if this line of the display
should not show any textjava.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display has or if it is negativegetText(int)
public void setText(int lineNumber, java.lang.String text, boolean blinking, boolean inverseColor) throws java.lang.ArrayIndexOutOfBoundsException
setText(lineNumber, text)
, but with the additional possibility to
determine whether the text should be displayed blinking and/or inversed.lineNumber
- the line number the text should be written to, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)text
- the new text to be displayed in the specified line of the
display, or null
if this line of the display
should not show any textblinking
- true
if text to be displayed should blink,
false
otherwise; if the physical display does
not offer this feature, this parameter is ignoredinverseColor
- true
if text to be displayed should be
shown inversed, means signs in backlight color on background
in text color; false
otherwise; if the physical
display does not offer this feature, this parameter is ignoredjava.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display has or if it is negativesetText(int, java.lang.String)
public int getChars(char[] data) throws java.lang.ArrayIndexOutOfBoundsException, java.lang.NullPointerException
data
- the character array to receive the valuejava.lang.ArrayIndexOutOfBoundsException
- if the array is too short for the contentsjava.lang.NullPointerException
- if data
is null
setChars(char[], int, int)
public int getChars(int lineNumber, char[] data) throws java.lang.ArrayIndexOutOfBoundsException, java.lang.NullPointerException
The line content can be more than what's visible at a certain moment if horizontal scrolling is available and active for this line.
lineNumber
- the line number the text should be copied from, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)data
- the character array to receive the valuejava.lang.ArrayIndexOutOfBoundsException
- if the array is too short for the contentsjava.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display hasjava.lang.NullPointerException
- if data
is null
setChars(char[], int, int)
public void setChars(char[] data, int offset, int length) throws java.lang.ArrayIndexOutOfBoundsException
data
array starting at array index offset
and running for length
characters. If the data array is
null
, the display text is set to be empty and
the other parameters are ignored.
The offset
and length
parameters must
specify a valid range of characters within the character array
data
. The offset
parameter must be within
the range [0..(data.length)]
, inclusive. The
length
parameter must be a non-negative integer such that
(offset + length) <= data.length
.
If the text contains more characters than the number that can
be shown by the display, it causes vertical scrolling, if the display is
able to scroll vertically and vertical scrolling mode is set active.
Otherwise the text is cut. Please be aware that the cut text is lost
in this case, even if scrolling mode is set active later! As a consequence
a subsequent call to the getText
method will not in all
cases return the text string that was the argument to this method.
Horizontal scrolling is disabled for any line by a call to this method, not depending on how the horizontal scrolling mode has been before for any display line.
For displaying of the new text, the whole display is used, means the complete former content of the Display (if any) is removed. If the number of characters that can be shown in one line is exceeded, the text continues in the next line (if any). No carriage returns (CRs) are inserted into the char array in order to wrap text to the next line. Instead the implementation is encouraged to develop it's own strategy to arrange the characters on several lines (if available). Where the text is wrapped is implemntation dependent, the implementation is not forced to use all characters of a line and wrap the text exactly at the end of the line. Depending on requirements of readability, the text could be wrapped e.g. where white characters like space or tab appear in the char array.
If the argument char array contains carrige returns (CRs), the behavior how these are handled is implementation dependent: Implementations are free to ignore CRs (means: replace them by simple spaces) or start indeed a new text line.
A possible way of implementation could be to internally "translate" a call
to setChars(char[] data, int offset, int length)
into an
appropriate number of calls to setChars(int lineNumber, char[] data,
int offset, int length)
.
data
- the source of the character dataoffset
- the beginning of the region of characters to copylength
- the number of characters to copyjava.lang.ArrayIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the data arraygetChars(char[])
public void setChars(char[] data, int offset, int length, boolean blinking, boolean inverseColor) throws java.lang.ArrayIndexOutOfBoundsException
setChars(data, offset, length)
, but with the additional possibility
to determine whether the text should be displayed blinking and/or
inversed.data
- the source of the character dataoffset
- the beginning of the region of characters to copylength
- the number of characters to copyblinking
- true
if text to be displayed should blink,
false
otherwise; if the physical display does
not offer this feature, this parameter is ignoredinverseColor
- true
if text to be displayed should be
shown inversed, means signs in backlight color on background
in text color; false
otherwise; if the physical
display does not offer this feature, this parameter is ignoredjava.lang.ArrayIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the data arraysetChars(char[], int, int)
public void setChars(int lineNumber, char[] data, int offset, int length) throws java.lang.ArrayIndexOutOfBoundsException
data
array starting at array index
offset
and running for length
characters. If the
data array is null
, the display text is set to be empty and
the other parameters are ignored.
The offset
and length
parameters must
specify a valid range of characters within the character array
data
. The offset
parameter must be within
the range [0..(data.length)]
, inclusive. The
length
parameter must be a non-negative integer such that
(offset + length) <= data.length
.
If the text contains more characters
than the number that can be shown by a single line of the display, it
causes horizontal scrolling, if the display is able to scroll horizontally
and horizontal scrolling mode is set active for this line. Otherwise the
text is cut, the excess characters MUST NOT be written into the next line.
Please be aware that the cut text is lost in this case, even if scrolling
mode is set active later! As a consequence a subsequent call to the
getText(int linenumber)
method will not in all
cases return the text string that was the argument to this method.
If the argument char array contains carriage returns (CRs), they MUST be ignored, means replaced by simple spaces.
If vertical scrolling is active, the line being in the position of the specified line number at the point of time the method is called is replaced. It is strongly recommended to deactivate scrolling before calling this method though!
lineNumber
- the line number the text should be copied to, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)data
- the source of the character data to be shown in the specified
lineoffset
- the beginning of the region of characters to copylength
- the number of characters to copyjava.lang.ArrayIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the data arrayjava.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display hasgetChars(int, char[])
public void setChars(int lineNumber, char[] data, int offset, int length, boolean blinking, boolean inverseColor) throws java.lang.ArrayIndexOutOfBoundsException
setChars(lineNumber, data, offset, length)
, but with the additional possibility
to determine whether the text should be displayed blinking and/or
inversed.lineNumber
- the line number the text should be copied to, must
be between zero (for the first line) and getNumberOfLines() - 1
(for the last line)data
- the source of the character data to be shown in the specified
lineoffset
- the beginning of the region of characters to copylength
- the number of characters to copyblinking
- true
if text to be displayed should blink,
false
otherwise; if the physical display does
not offer this feature, this parameter is ignoredinverseColor
- true
if text to be displayed should be
shown inversed, means signs in backlight color on background
in text color; false
otherwise; if the physical
display does not offer this feature, this parameter is ignoredjava.lang.ArrayIndexOutOfBoundsException
- if offset
and length
do not
specify a valid range within the data arrayjava.lang.ArrayIndexOutOfBoundsException
- if the specified line number
is greater than or equal to the actual number of lines this
display hassetChars(int, char[], int, int)
public int getVerticalScrollingInterval()
public int getHorizontalScrollingInterval(int lineNumber)
lineNumber
- the line Number the horizontal scrolling interval is
retrieved for; must be between zero (for the first line) and
getNumberOfLines() - 1
(for the last line)public void setVerticalScrollingInterval(int interval) throws java.lang.IllegalArgumentException
interval
- the number of milliseconds between line shifts if vertical
scrolling is supported by this display and enabled; must be greater
or equal to zero, while zero means fastest scrollingjava.lang.IllegalArgumentException
- if interval
has a negative
valuepublic void setHorizontalScrollingInterval(int lineNumber, int interval) throws java.lang.IllegalArgumentException
lineNumber
- the line number for which the horizontal scrolling
interval should be set; must be between zero (for the first line) and
getNumberOfLines() - 1
(for the last line)interval
- the number of milliseconds between character shifts if
horizontal scrolling is supported by this display and enbaled for
the specified line; must be greater or equal to zero, while zero
means fastest scrollingjava.lang.IllegalArgumentException
- if lineNumber
is out of
the scope defined above, or if interval
has a negative
valuepublic boolean isBacklightColorsSupported()
true
if the display supports backlight colors,
false
otherwisepublic DisplayColor getBacklightColor()
isBacklightColorsSupported()
returns false
, the
return value is always the value of BACKLIGHT_STANDARD_COLOR
.
If backlight is not supported by this display at all, this value has no
particular meaning.
Please notice, that this method always returns the actual
currently valid backlight color, which has not necessarily to be the one
that was the argument to a previously processed call to
setBacklightColor
as implementations of that method are assumed to
choose the one of the available colors being closest to the argument
value in case freely configurable colors are not supported.
public DisplayColor setBacklightColor(DisplayColor color)
Without a call to this method, the current backlight color is always
BACKLIGHT_STANDARD_COLOR
.
If the display supports freely configurable colors as defined by the RGB model, it is assumed that the backlight after this call has the configured color. If the display only supports a limited number of backlight colors, implementations are assumed to choose the one of the available colors being closest to the configured value.
If the display does not support backlight colors, i.e. if a call to
isBacklightColorsSupported()
returns false
, a call to
this method has no effect and BACKLIGHT_STANDARD_COLOR
is returned.
color
- the new backlight color for the displaypublic java.lang.String getDisplayId()
Display
.
This Id can be used by applications to identify a certain display in
cases where the originally retrived object reference of the Display
object is not stored by the application for memory performance reasons.Display
Copyright (c) 2013, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.