net.rim.device.api.system
Class Display
java.lang.Object
net.rim.device.api.system.Display
public final class Display
- extends Object
Provides access to the BlackBerry device’s screen properties. You can use this class to access information
such as screen size, dimensions, orientation, backlight, and subpixel support. To configure your
application to only allow specific screen properties, use the various methods available in Ui
.
NOTE: A distinction is made between screen orientation and direction.
Orientation refers to the following BlackBerry device screen aspect ratios:
To retrieve information on current orientation, invoke Display.getOrientation()
.
Direction refers to the top of the drawing area of the screen, which is always relative to the location
of the BlackBerry logo. That is:
You can configure your application to only allow specific orientations by passing in specific direction parameters
when invoking UiEngineInstance.setAcceptableDirections(int)
.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
Field Summary |
|
static int |
DIRECTION_EAST
A direction the BlackBerry device screen can support. |
|
static int |
DIRECTION_LANDSCAPE
A direction the BlackBerry device screen can support. |
|
static int |
DIRECTION_NORTH
A supported direction for the BlackBerry device screen where the top of the screen is on the same side as the "BlackBerry" logo at the top of the device
. |
|
static int |
DIRECTION_PORTRAIT
A direction the BlackBerry device screen can support. |
|
static int |
DIRECTION_WEST
A direction the BlackBerry device screen can support. |
|
static int |
DISPLAY_PROPERTY_NO_SUBPIXELS
Sets the BlackBerry device screen to not support subpixels. |
|
static int |
DISPLAY_PROPERTY_REQUIRES_BACKLIGHT
Sets the BlackBerry device screen use to use the backlight. |
|
static int |
ORIENTATION_LANDSCAPE
The aspect ratio of the BlackBerry device's screen in the current direction where the vertical resolution is larger than the horizontal resolution. |
|
static int |
ORIENTATION_PORTRAIT
The aspect ratio of the BlackBerry device's screen in the current direction where the horizontal resolution is larger than the vertical resolution. |
|
static int |
ORIENTATION_SQUARE
The aspect ratio of the BlackBerry device's screen in the current direction where both the vertical and horizontal resolution are equal. |
Method Summary |
|
static int |
getContrast()
Deprecated. |
|
static int |
getContrastIncrement()
Deprecated. |
|
static int |
getHeight()
Retrieves the total drawing height of the display. |
|
static int |
getHorizontalResolution()
Retrieves the display's horizontal resolution (in pixels per meter, or PPM). |
|
static int |
getNumColors()
Retrieves the number of colors that the BlackBerry device screen can display. |
|
static int |
getOrientation()
Retrieves the graphic aspect ratio of the BlackBerry device screen based on number
of horizontal versus vertical pixels. |
|
static int |
getProperties()
Retrieves the display properties. |
|
static int |
getVerticalResolution()
Retrieves the display's vertical resolution (in pixels per meter, or PPM). |
|
static int |
getWidth()
Retrieves the total drawing width of the display. |
|
static boolean |
isColor()
Determines if the BlackBerry device has a color display. |
|
static boolean |
isContrastConfigurable()
Deprecated. |
|
static boolean |
isRowwise()
Determines if the BlackBerry device's display has Rowwise orientation. |
|
static void |
screenshot(Bitmap bitmap)
Takes a screenshot of the entire screen and saves it into a Bitmap . |
|
static void |
screenshot(Bitmap bitmap,
int x,
int y,
int width,
int height)
Takes a screenshot of a portion of the screen and saves it into a Bitmap . |
|
static void |
setContrast(int contrast)
Deprecated. |
DISPLAY_PROPERTY_NO_SUBPIXELS
public static final int DISPLAY_PROPERTY_NO_SUBPIXELS
- Sets the BlackBerry device screen to not support subpixels.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.1.0
DISPLAY_PROPERTY_REQUIRES_BACKLIGHT
public static final int DISPLAY_PROPERTY_REQUIRES_BACKLIGHT
- Sets the BlackBerry device screen use to use the backlight.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.1.0
DIRECTION_NORTH
public static final int DIRECTION_NORTH
- A supported direction for the BlackBerry device screen where the top of the screen is on the same side as the "BlackBerry" logo at the top of the device
. To set the allowable directions for your application, pass in specific direction parameters
when invoking
UiEngineInstance.setAcceptableDirections(int)
.
DIRECTION_NORTH
corresponds to the direction when the top of the screen is on the same side as the
"BlackBerry" logo at the top of the BlackBerry device.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
DIRECTION_EAST
public static final int DIRECTION_EAST
- A direction the BlackBerry device screen can support. To set the allowable directions for your application, pass in specific direction parameters
when invoking
UiEngineInstance.setAcceptableDirections(int)
.
DIRECTION_EAST
corresponds to the direction when the top of the screen is 90 degrees to the left of the
"BlackBerry" logo at the top of the BlackBerry device.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
DIRECTION_WEST
public static final int DIRECTION_WEST
- A direction the BlackBerry device screen can support. To set the allowable directions for your application, pass in specific direction parameters
when invoking
UiEngineInstance.setAcceptableDirections(int)
.
DIRECTION_WEST
corresponds to the direction when the top of the screen is 90 degrees to the right of the
"BlackBerry" logo at the top of the BlackBerry device.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
DIRECTION_LANDSCAPE
public static final int DIRECTION_LANDSCAPE
- A direction the BlackBerry device screen can support. To set the allowable directions for your application, pass in specific direction parameters
when invoking
UiEngineInstance.setAcceptableDirections(int)
.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
DIRECTION_PORTRAIT
public static final int DIRECTION_PORTRAIT
- A direction the BlackBerry device screen can support. To set the allowable directions for your application, pass in specific direction parameters
when invoking
UiEngineInstance.setAcceptableDirections(int)
.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
ORIENTATION_SQUARE
public static final int ORIENTATION_SQUARE
- The aspect ratio of the BlackBerry device's screen in the current direction where both the vertical and horizontal resolution are equal.
Display.getOrientation()
returns this value if invoked when the BlackBerry device screen resolution is the same vertically and horizontally.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
ORIENTATION_LANDSCAPE
public static final int ORIENTATION_LANDSCAPE
- The aspect ratio of the BlackBerry device's screen in the current direction where the vertical resolution is larger than the horizontal resolution.
Display.getOrientation()
returns this value if invoked when the BlackBerry device screen horizontal resolution is larger than the vertical
resolution.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
ORIENTATION_PORTRAIT
public static final int ORIENTATION_PORTRAIT
- The aspect ratio of the BlackBerry device's screen in the current direction where the horizontal resolution is larger than the vertical resolution.
Display.getOrientation()
returns this value if invoked when the BlackBerry device screen vertical resolution is larger than the horizontal
resolution.
- See Also:
- Constant Field Values
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
getContrast
public static int getContrast()
- Deprecated.
- Retrieves the screen's current contrast setting.
Use this method to retrieve the screen's contrast setting. The
returned value ranges from 0 (lightest) to 100 (darkest).
- Returns:
- Current screen contrast setting.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getContrastIncrement
public static int getContrastIncrement()
- Deprecated.
- Retrieves the recommended percentage increment for display contrast.
Externally, we show display contrast as a percentage, but internally
the range will vary between device types. The increment is rounded down
to the nearest integer. For example, if the device range is 7, the
increment would be 14.
- Returns:
- An increment value between 1 and 100.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getHeight
public static int getHeight()
- Retrieves the total drawing height of the display.
- Returns:
- Height (in pixels) of the display's drawable area.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getHorizontalResolution
public static int getHorizontalResolution()
- Retrieves the display's horizontal resolution (in pixels per meter, or PPM).
- Returns:
- Horizontal display resolution (in pixels per meter, or PPM) of the display.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getNumColors
public static int getNumColors()
- Retrieves the number of colors that the BlackBerry device screen can display.
- Returns:
- Number of colors the BlackBerry device screen can display.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getOrientation
public static int getOrientation()
- Retrieves the graphic aspect ratio of the BlackBerry device screen based on number
of horizontal versus vertical pixels.
- Returns:
Display.ORIENTATION_LANDSCAPE
, Display.ORIENTATION_PORTRAIT
, or Display.ORIENTATION_SQUARE
.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.7.0
getProperties
public static int getProperties()
- Retrieves the display properties.
- Returns:
- A combination of the
DISPLAY_PROPERTY_*
values. - Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.1.0
getVerticalResolution
public static int getVerticalResolution()
- Retrieves the display's vertical resolution (in pixels per meter, or PPM).
- Returns:
- Vertical screen resolution (in pixels per meter, or PPM).
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
getWidth
public static int getWidth()
- Retrieves the total drawing width of the display.
- Returns:
- Width (in pixels) of the display's drawable area.
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
isColor
public static boolean isColor()
- Determines if the BlackBerry device has a color display.
- Returns:
true
if the BlackBerry device has a color display; false
otherwise.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
isContrastConfigurable
public static boolean isContrastConfigurable()
- Deprecated.
- Retrieves whether or not the BlackBerry device's screen contrast is configurable.
- Returns:
true
if the BlackBerry device's screen contrast can be set; false
otherwise.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
isRowwise
public static boolean isRowwise()
- Determines if the BlackBerry device's display has Rowwise orientation.
- Returns:
true
if the BlackBerry device's display has a Rowwise orientation; false
otherwise.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.1.0
setContrast
public static void setContrast(int contrast)
- Deprecated.
- Sets the display's current contrast setting.
- Parameters:
contrast
- New contrast value for screen.- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.0.0
screenshot
public static void screenshot(Bitmap bitmap)
- Takes a screenshot of the entire screen and saves it into a
Bitmap
.
The specified Bitmap
must be the same dimensions as the screen. The value that represents
the width and height of the screen can be obtained from Display.getWidth()
and Display.getHeight()
,
respectively. The width and height of the Bitmap
must be equal to this value.
The type of the specified Bitmap
must match the screen type. The following
methods can be used to determine the screen's properties:
- Parameters:
bitmap
- The Bitmap
into which the screenshot is saved.
- Throws:
ControlledAccessException
- if the calling application is forbidden from taking screenshots
by IT policy and/or application control.
IllegalArgumentException
- if any of the following conditions are true:
bitmap
is null
- The dimensions of
bitmap
are not equal to the dimensions of the screen
- The type of
bitmap
does not match the type of the screen
- See Also:
Display.screenshot(Bitmap, int, int, int, int)
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.3.0
screenshot
public static void screenshot(Bitmap bitmap,
int x,
int y,
int width,
int height)
- Takes a screenshot of a portion of the screen and saves it into a
Bitmap
.
The dimensions of the specified Bitmap
must be large enough to hold the specified
region; that is, the width and height of bitmap
must be at least the specified
width
and height
, respectively.
The specified region (the box represented by x
, y
,
width
, and height
) must be fully contained in the screen.
This region is copied into the specified Bitmap
starting at (0, 0).
The type of the specified Bitmap
must match the type of the screen. The following
methods can be used to determine the screen's properties:
- Parameters:
bitmap
- The Bitmap
into which the screenshot is saved.x
- The x-coordinate of the screen that marks the top-left corner of the region to be copied.y
- The y-coordinate of the screen that marks the top-left corner of the region to be copied.width
- The width of the region of the screen to be copied.height
- The height of the region of the screen to be copied.
- Throws:
ControlledAccessException
- if the calling application is forbidden from taking screenshots
by IT policy and/or application control.
IllegalArgumentException
- if any of the following conditions are true:
bitmap
is null;
- The dimensions of
bitmap
are not large enough to hold the specified region;
- The type of
bitmap
does not match the type of the screen;
- The value of any of the integer arguments are less than zero; or
- The specified region is not fully contained on the screen.
- See Also:
Display.screenshot(Bitmap)
- Category:
- Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
- Since:
- BlackBerry API 4.3.0
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.