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 Display via an associated
KeyListener
, as defined in the javax.microedition.key
package. A Display that supports key events, MUST implement the
InputDevice
interface as defined in the
javax.microedition.key package. This implies of course that this optional
package would have to be implemented by the MEEP 8 implementation.
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, in principle, the following should be true.
A Display
may be 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.
A Display
may be unassigned to the corresponding display resource.
Then 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
setHardwareAssigned
method. However, these requests to change the state are not guaranteed and are
subject to the device's application display sharing management behavior.
For an application, there may be a primary Display
object. The primary Display
corresponds to the device's main
(built-in) display, if any, that is normally used to access its features.
Note that devices may have only auxiliary displays. As auxiliary displays
are only temporarily attached to the device, in this case there is not always
a display available. Of course it makes nmo sense to mention a primary display
in this case.
The getDisplays(boolean)
method returns a list of
Display
objects corresponding to a given application. The primary
Display
object, if any and 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).
Note that displays supporting key events require the implementation of the
optional javax.microedition.key
package (see
optionality chapter for details), and that those displays MUST
implement the InputDevice
interface.
Besides a line-oriented display may support several text colors, or just a single color. Display can also support background color with or without the ability of change as well as lighting with a fixed color or the capability to change lighting color as well.
The Display
class also defines name and values for events that can
be used to handle lighting of displays (if supported by a paticular Display)
using the Event
class.
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 |
LIGHTING
To be used as an event name for
Event . |
static int |
LIGHTING_DIM
Valid value for
LIGHTING events. |
static int |
LIGHTING_OFF
Valid value for
LIGHTING events. |
static int |
LIGHTING_ON
Valid value for
LIGHTING events. |
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.
|
Modifier and Type | Method and Description |
---|---|
static void |
addDisplayListener(DisplayListener l)
Adds a display listener to receive Display notifications.
|
DisplayColor |
getBackgroundColor()
Retrieves the currently valid background 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.
|
DisplayColor |
getDefaultBackgroundColor()
Default background color for this display.
|
DisplayColor |
getDefaultLightingColor()
Default lighting color for this dsiplay.
|
DisplayColor |
getDefaultTextColor()
Return the default text color for this display.
|
static java.util.Iterator<Display> |
getDisplays(boolean keyEventSupport)
Gets a list of all available
Display s for this application. |
int |
getHorizontalScrollingInterval(int lineNumber)
Retrieves horizontal scrolling interval for the specified line of this
display in milliseconds between character shifts.
|
java.lang.String |
getId()
Retrieves an implementation-specific Id for this
Display . |
DisplayColor |
getLightingColor()
Retrieves the currently valid lighting color of the display.
|
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 |
isBackgroundColorsSupported()
Gets information about background color support by the display.
|
boolean |
isBuiltIn()
Checks if this display's hardware is Built-In or Auxiliary.
|
boolean |
isHardwareAssigned()
Checks wether this
Display has access to the
underlying hardware. |
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 |
isLightingColorsSupported()
Gets information about lighting color change support by the display.
|
boolean |
isLightingSupported()
Gets information about lighting support by the display.
|
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.
|
static void |
removeDisplayListener(DisplayListener l)
Removes a previously added display listener.
|
DisplayColor |
setBackgroundColor(DisplayColor color)
Sets the background 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 |
setHardwareAssigned(boolean state)
Allows the application to request that a
Display becomes
assigned or unassigned to the underlying hardware. |
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 |
setHorizontalScrolling(int lineNumber,
boolean scrollEnable,
boolean direction)
Enables or disables horizontal scrolling for the specified line of the
display in the specified direction 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.
|
DisplayColor |
setLightingColor(DisplayColor color)
Sets the lighting color to be used by the display from now on.
|
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 |
setVerticalScrolling(boolean scrollEnable,
boolean direction)
Enables or disables vertical scrolling for the display in the specified
direction 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 LIGHTING
Event
.
Indicates the lighting level.
The value SHOULD NOT be changed due to any programmatic
flashing of the lighting through any other API.
The value is an integer with values:
LIGHTING_ON
, LIGHTING_OFF
, or
LIGHTING_DIM
.public static final int LIGHTING_OFF
LIGHTING
events.
Indicates the lighting is off.LIGHTING
,
Constant Field Valuespublic static final int LIGHTING_ON
LIGHTING
events.
Indicates the lighting is on.LIGHTING
,
Constant Field Valuespublic static final int LIGHTING_DIM
LIGHTING
events.
Indicates the lighting is dim. Any illumination level other
than fully on or off MUST be reported as dim.LIGHTING
,
Constant Field Valuespublic 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 DisplayColor getDefaultTextColor()
public DisplayColor getDefaultBackgroundColor()
public DisplayColor getDefaultLightingColor()
public static java.util.Iterator<Display> getDisplays(boolean keyEventSupport)
Display
s for this application.
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 there is a primary display, and it is
available and therefore 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.
Note that displays supporting key events require the implementation of the
optional javax.microedition.key
package (see
optionality chapter for details), and that those displays MUST
implement the InputDevice
interface.
Note that independent on the value of the parameter, the result list may be empty, in case displays are unavailable at the time the method is called because
Display
explicitly using
isHardwareAssigned()
before doing any actions
with it.keyEventSupport
- true
if only Display
s supporting key
events should be listed, false
to list all
Display
sDisplay
s. The list
the iterator refers to may be empty and will never contain
two displays with the same id.public static void addDisplayListener(DisplayListener l)
Displays
. If this
listener had already been added, the call has no effect.l
- the new listener to be addedjava.lang.NullPointerException
- if the listener is nullpublic static void removeDisplayListener(DisplayListener l)
l
- the listener to be removedjava.lang.NullPointerException
- if the listener is nullpublic 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 same as for getDefaultTextColor()
.
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 the default
text color of this display as returned by a call to
getDefaultTextColor()
.
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 text colors, i.e. if a call to
isTextColorsSupported()
returns false
, a call to
this method has no effect and the return value is the same like the one
of getDefaultTextColor()
.
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) throws java.lang.ArrayIndexOutOfBoundsException
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
otherwisejava.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 negativepublic void setVerticalScrolling(boolean scrollEnable)
isVerticalScrollingSupported()
returns
false
, a call to this method is ignored.
The value of the scrolling interval is zero, which means fastest scrolling.
It can be changed using setVerticalScrolling
method.
If the display supports vertical scrolling only in one direction, than this direction is chosen. If vertical scrolling in both directions is supported, then a call to this method initates scrolling top down.
scrollEnable
- true
to enable vertical scrolling,
false
to disable vertical scrollingpublic void setVerticalScrolling(boolean scrollEnable, boolean direction)
isVerticalScrollingSupported()
returns false
, a call to this method is ignored.
The value of the scrolling interval is zero, which means fastest scrolling.
It can be changed using setVerticalScrolling
method.
In case vertical scrolling is supported by the display, but only in one direction, then the specified direction is ignored, and scrolling in the supported direction is initated.
scrollEnable
- true
to enable vertical scrolling,
false
to disable vertical scrollingdirection
- The desired direction of the vertical scrolling in the
specified line. true
means scrolling top down,
false
means scrolling bottom up.
This parameter is ignored, if only one direction is supported for
vertical scrolling: in this case the supported direction is
chosen.public void setHorizontalScrolling(int lineNumber, boolean scrollEnable) throws java.lang.ArrayIndexOutOfBoundsException
isHorizontalScrollingSupported()
returns false
, a call to this method is ignored.
The value of the scrolling interval is zero, which means fastest scrolling.
It can be changed using setHorizontalScrolling
method.
If the display supports horizontal scrolling only in one direction, than this direction is chosen. If horizontal scrolling in both directions is supported, then a call to this method initates scrolling from left to right.
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 scrollingjava.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 negativepublic void setHorizontalScrolling(int lineNumber, boolean scrollEnable, boolean direction) throws java.lang.ArrayIndexOutOfBoundsException
isHorizontalScrollingSupported()
returns false
, a call to
this method is ignored.
The value of the scrolling interval is zero, which means fastest scrolling.
It can be changed using setHorizontalScrolling
method.
In case horizontal scrolling is supported by the display, but only in one direction, then the specified direction is ignored, and scrolling in the supported direction is initated.
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 scrollingdirection
- The desired direction of the horizontal scrolling in the
specified line. true
means scrolling from left to
right, false
means scrolling from right to left.
This parameter is ignored, if only one direction is supported for
horizontal scrolling: in this case the supported direction is
chosen.java.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 negativepublic boolean isHardwareAssigned()
Display
has access to the
underlying hardware. If the Display
implements
the InputDevice
interface, i.e. if it has user input
capabilities, this method is the implementation of the respective
one in the InputDevice
interface, as the status is
valid for both then, the Display
and its user
input device.true
if the Display
has access to
the underlying hardware, false
otherwisepublic void setHardwareAssigned(boolean state)
Display
becomes
assigned or unassigned to the underlying hardware. However, a requests to
change the Display
state is not guaranteed and subject to
the device's application display sharing management behavior.
A call to setHardwareAssigned(false)
has no effect on the text
shown at the display as long as the display isn't unassigned indeed. As
soon as this happens, all content of the display is lost.
A call to setHardwareAssigned(true)
has no effect on the text
shown by the display if the display has already been assigned before. If
the display will be assigned by this call though, it won't show any text.
With other words, unassigning and assigning a display causes the text
shown there to be removed.
Please note, that - depending on the physical structure of the device -
a display may have also become unassigned by physical separation from the
device without a call to setHardwareAssigned(false)
. In
this case, the text shown there is lost as well of course, and - after the
physical connection has been restored - a call to setHardwareAssigned(true)
may be necessary in order to re-assign it (the exact behavior in
this case is implementation-dependent).
If the Display
implements the InputDevice
interface,
i.e. if it has user input capabilities, this method is the implementation
of the respective one in the InputDevice
interface, as the
status is valid for both then, the Display
and its user
input device.
state
- true
in order to explicitly assign the underlying
hardware, false
otherwisepublic boolean isBuiltIn()
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()
Depending on implementation-dependent handling of non-visible text and
scrolling mode, 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.
If an implementation decides to cut text set by
setText
not fitting into the display
if scrolling is disabled, the result of this method MAY differ from what
has been the argument to a previous call to
setText
.
setText(null)
or
setText("")
setText(java.lang.String)
public java.lang.String getText(int lineNumber) throws java.lang.ArrayIndexOutOfBoundsException
ArrayIndexOutOfBoundsException
is thrown.
Depending on implementation-dependent handling of non-visible text and scrolling mode, 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!
If an implementation decides to cut text set by
setText(lineNumber, text)
not fitting into the display
if scrolling is disabled, the result of this method MAY differ from what
has been the argument to a previous call to
setText(lineNumber, text)
.
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)setText(lineNumber, null)
or
setText(lineNumber, "")
java.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(java.lang.String)
public void setText(java.lang.String text)
getText()
method will not for all implementations 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). 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: display simple spaces instead) or start indeed a new text line. By no means the implementation is allowed to physically change the text by actually adding, removing or replacing characters.
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 text
(setText(null)
and setText("")
has a similar effect)getText()
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 text
(setText(null, ...)
and
setText("", ...)
has a similar effect)blinking
- 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 background 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
for all implementations 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 simple spaces must be displayed instead.
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 text (setText(lineNumber, null)
and setText(lineNumber, "")
has a similar effect)java.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 text (setText(lineNumber, null, ...)
and setText(lineNumber, "", ...)
has a similar effect)blinking
- 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 background 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
setText
not fitting into the display
if scrolling is disabled, the result of this method MAY differ from what
has been the argument to a previous call to
setText
.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
Dependent on implementation-dependent handling of non-visible text and
scrolling mode, the line content can be more than what's visible at a
certain moment.
If an implementation decides to cut text set by
setText(lineNumber, text)
not fitting into the display
if scrolling is disabled, the result of this method MAY differ from what
has been the argument to a previous call to
setText(lineNumber, text)
.
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 has, or if it is negativejava.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) - 1]
. 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 excess characters are invisible. Please be aware that, dependent
on the implementation, those excess characters MAY be lost in this case,
even if scrolling mode is set active later! As a consequence a subsequent
call to the getText()
method will not
for all implementations 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). 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 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: means: display simple spaces instead) or start indeed a new text line. By no means the implementation is allowed to physically change the text by actually adding, removing or replacing characters.
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 background 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) - 1]
. 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 excess characters are invisible and
MUST NOT be written into the next line. Please be aware that, dependent
on the implementation, those excess characters MAY be 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
for all implementations 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 simple spaces displayed instead.
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 has, or if it is negativegetChars(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 background 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 has or if it is negativesetChars(int, char[], int, int)
public int getVerticalScrollingInterval()
public int getHorizontalScrollingInterval(int lineNumber) throws java.lang.ArrayIndexOutOfBoundsException
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)java.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 negativepublic 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, java.lang.ArrayIndexOutOfBoundsException
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 enabled for
the specified line; must be greater or equal to zero, while zero
means fastest scrollingjava.lang.IllegalArgumentException
- if interval
has a negative
valuejava.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 negativepublic boolean isBackgroundColorsSupported()
true
if the display supports background colors,
false
otherwisepublic boolean isLightingSupported()
true
if the display supports lighting,
false
otherwisepublic boolean isLightingColorsSupported()
true
if the display supports change of lighting color,
false
otherwisepublic DisplayColor getBackgroundColor()
isBackgroundColorsSupported()
returns false
, the
return value is always the same as for getDefaultBackgroundColor()
.
If background colors 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 background color, which has not necessarily to be the one
that was the argument to a previously processed call to
setBackgroundColor
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 setBackgroundColor(DisplayColor color)
Without a call to this method, the current background color is always
the return value of getDefaultBackgroundColor()
.
If the display supports freely configurable colors as defined by the RGB model, it is assumed that the background after this call has the configured color. If the display only supports a limited number of background colors, implementations are assumed to choose the one of the available colors being closest to the configured value.
If the argument is null
, then the method switches off
background illumination (if supported).
If background illumination is supported, but switched off, a call to this method with a non-null argument switches the background illumination on.
If the display does not support background colors, i.e. if a call to
isBackgroundColorsSupported()
returns false
, a call to
this method has no effect and the same value as for
getDefaultBackgroundColor()
is returned.
color
- the new background color for the display, or null
to switch off background illuminationpublic DisplayColor getLightingColor()
isLightingColorsSupported()
returns false
, the
return value is always the same as the one for a call to
getDefaultLightingColor()
.
If a call to isLightingSupported()
returns false
,
means if lighting is not supported by this display at all, the same value
is returned, but has no particular meaning.
Please notice, that this method always returns the actual
currently valid lighting color, which has not necessarily to be the one
that was the argument to a previously processed call to
setLightingColor
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 setLightingColor(DisplayColor color)
Without a call to this method, the current lighting color is always
the return value of getDefaultLightingColor()
.
If lighting is not supported by the display, a call to this method has no effect.
If the display supports freely configurable colors as defined by the RGB model, it is assumed that the lighting after this call has the configured color. If the display only supports a limited number of lighting colors, implementations are assumed to choose the one of the available colors being closest to the configured value.
If the argument is null
, then the method switches off
lighting (if supported).
If lighting is supported, but switched off, a call to this method with a non-null argument switches the lighting on.
If the display does not support lighting colors, i.e. if a call to
isLightingColorsSupported()
returns false
, a call to
this method has no effect and the same value as for
getDefaultLightingColor()
is returned.
If a call to isLightingSupported()
returns false
,
means if lighting is not supported by this display at all, the same value
is returned, but has no particular meaning.
color
- the new lighting color for the display, or null
to switch off lightingpublic java.lang.String getId()
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.
Note that, if a display implements the InputDevice
interface,
this method is the implementation of InputDevice.getId()
, so the returned display id is also the input device
id and vice versa.
Display
, MUST NOT be null or emptyCopyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.