Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.swt.graphics
Class Device

    java.lang.Object
      org.eclipse.swt.graphics.Device

All Implemented Interfaces:
  Drawable

Direct Known Subclasses:
  Display, Printer

public abstract class Device
extends Object
implements Drawable

This class is the abstract superclass of all device objects, such as the Display device and the Printer device. Devices can have a graphics context (GC) created for them, and they can be drawn on by sending messages to the associated GC.

Field Summary
`protected static Device` | `CurrentDevice`
`static boolean` | `DEBUG`
`protected static Runnable` | `DeviceFinder`
`int` | `hPalette`

Constructor Summary
`Device(DeviceData data)` Constructs a new instance of this class.

Method Summary
`protected void` | `checkDevice()` Throws an `SWTException` if the receiver can not be accessed by the caller.
`protected void` | `create(DeviceData data)` Creates the device in the operating system.
`protected void` | `destroy()` Destroys the device in the operating system and releases the device's handle.
`void` | `dispose()` Disposes of the operating system resources associated with the receiver.
`Rectangle` | `getBounds()` Returns a rectangle describing the receiver's size and location.
`Rectangle` | `getClientArea()` Returns a rectangle which describes the area of the receiver which is capable of displaying data.
`int` | `getDepth()` Returns the bit depth of the screen, which is the number of bits it takes to represent the number of unique colors that the screen is currently capable of displaying.
`DeviceData` | `getDeviceData()` Returns a `DeviceData` based on the receiver.
`Point` | `getDPI()` Returns a point whose x coordinate is the horizontal dots per inch of the display, and whose y coordinate is the vertical dots per inch of the display.
`FontData[]` | `getFontList(String faceName, boolean scalable)` Returns `FontData` objects which describe the fonts that match the given arguments.
`Color` | `getSystemColor(int id)` Returns the matching standard color for the given constant, which should be one of the color constants specified in class `SWT`.
`Font` | `getSystemFont()` Returns a reasonable font for applications to use.
`boolean` | `getWarnings()` Returns `true` if the underlying window system prints out warning messages on the console, and `setWarnings` had previously been called with `true`.
`protected void` | `init()` Initializes any internal resources needed by the device.
`abstract void` | `internal_dispose_GC(int hDC, GCData data)` Invokes platform specific functionality to dispose a GC handle.
`abstract int` | `internal_new_GC(GCData data)` Invokes platform specific functionality to allocate a new GC handle.
`boolean` | `isDisposed()` Returns `true` if the device has been disposed, and `false` otherwise.
`protected void` | `release()` Releases any internal resources back to the operating system and clears all fields except the device handle.
`void` | `setWarnings(boolean warnings)` If the underlying window system supports printing warning messages to the console, setting warnings to `true` prevents these messages from being printed.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEBUG

    public static boolean DEBUG

### hPalette

    public int hPalette

### CurrentDevice

    protected static Device CurrentDevice

### DeviceFinder

    protected static Runnable DeviceFinder

Constructor Detail

### Device

    public Device(DeviceData data)

  Constructs a new instance of this class.

  You must dispose the device when it is no longer required.

Parameters:
  `data` - the DeviceData which describes the receiver
See Also:
  `create(org.eclipse.swt.graphics.DeviceData)`, `init()`, `DeviceData`

Method Detail

### checkDevice

    protected void checkDevice()

  Throws an `SWTException` if the receiver can not be accessed by the caller. This may include both checks on the state of the receiver and more generally on the entire execution context. This method should be called by device implementors to enforce the standard SWT invariants.

  Currently, it is an error to invoke any method (other than `isDisposed()` and `dispose()`) on a device that has had its `dispose()` method called.

  In future releases of SWT, there may be more or fewer error checks and exceptions may be thrown for different reasons.

  Throws:
    `SWTException` -
    - ERROR_WIDGET_DISPOSED - if the receiver has been disposed

### create

    protected void create(DeviceData data)

  Creates the device in the operating system. If the device does not have a handle, this method may do nothing depending on the device.

  This method is called before `init`.

  Subclasses are supposed to reimplement this method and not call the `super` implementation.

  Parameters:
    `data` - the DeviceData which describes the receiver
  See Also:
    `init()`

### destroy

    protected void destroy()

  Destroys the device in the operating system and releases the device's handle. If the device does not have a handle, this method may do nothing depending on the device.

  This method is called after `release`.

  Subclasses are supposed to reimplement this method and not call the `super` implementation.

  See Also:
    `dispose()`, `release()`

### dispose

    public void dispose()

  Disposes of the operating system resources associated with the receiver. After this method has been invoked, the receiver will answer `true` when sent the message `isDisposed()`.

  See Also:
    `release()`, `destroy()`, `checkDevice()`

### getBounds

    public Rectangle getBounds()

  Returns a rectangle describing the receiver's size and location.

  Returns:
    the bounding rectangle
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getDeviceData

    public DeviceData getDeviceData()

  Returns a `DeviceData` based on the receiver. Modifications made to this `DeviceData` will not affect the receiver.

  Returns:
    a `DeviceData` containing the device's data and attributes
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  See Also:
    `DeviceData`

### getClientArea

    public Rectangle getClientArea()

  Returns a rectangle which describes the area of the receiver which is capable of displaying data.

  Returns:
    the client area
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  See Also:
    `getBounds()`

### getDepth

    public int getDepth()

  Returns the bit depth of the screen, which is the number of bits it takes to represent the number of unique colors that the screen is currently capable of displaying. This number will typically be one of 1, 8, 15, 16, 24 or 32.

  Returns:
    the depth of the screen
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getDPI

    public Point getDPI()

  Returns a point whose x coordinate is the horizontal dots per inch of the display, and whose y coordinate is the vertical dots per inch of the display.

  Returns:
    the horizontal and vertical DPI
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getFontList

    public FontData[] getFontList(String faceName,
                                  boolean scalable)

  Returns `FontData` objects which describe the fonts that match the given arguments. If the `faceName` is null, all fonts will be returned.

  Parameters:
    `faceName` - the name of the font to look for, or null
    `scalable` - if true only scalable fonts are returned, otherwise only non-scalable fonts are returned.
  Returns:
    the matching font data
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getSystemColor

    public Color getSystemColor(int id)

  Returns the matching standard color for the given constant, which should be one of the color constants specified in class `SWT`. Any value other than one of the SWT color constants which is passed in will result in the color black. This color should not be free'd because it was allocated by the system, not the application.

  Parameters:
    `id` - the color constant
  Returns:
    the matching color
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  See Also:
    `SWT`

### getSystemFont

    public Font getSystemFont()

  Returns a reasonable font for applications to use. On some platforms, this will match the "default font" or "system font" if such can be found. This font should not be free'd because it was allocated by the system, not the application.

  Typically, applications which want the default look should simply not set the font on the widgets they create. Widgets are always created with the correct default font for the class of user-interface component they represent.

  Returns:
    a font
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getWarnings

    public boolean getWarnings()

  Returns `true` if the underlying window system prints out warning messages on the console, and `setWarnings` had previously been called with `true`.

  Returns:
    `true`if warnings are being handled, and `false` otherwise
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### init

    protected void init()

  Initializes any internal resources needed by the device.

  This method is called after `create`.

  If subclasses reimplement this method, they must call the `super` implementation.

  See Also:
    `create(org.eclipse.swt.graphics.DeviceData)`

### internal_new_GC

    public abstract int internal_new_GC(GCData data)

  Invokes platform specific functionality to allocate a new GC handle.

  IMPORTANT: This method is not part of the public API for `Device`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

  Specified by:
    `internal_new_GC` in interface `Drawable`
  Parameters:
    `data` - the platform specific GC data
  Returns:
    the platform specific GC handle

### internal_dispose_GC

    public abstract void internal_dispose_GC(int hDC,
                                             GCData data)

  Invokes platform specific functionality to dispose a GC handle.

  IMPORTANT: This method is not part of the public API for `Device`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

  Specified by:
    `internal_dispose_GC` in interface `Drawable`
  Parameters:
    `hDC` - the platform specific GC handle
    `data` - the platform specific GC data

### isDisposed

    public boolean isDisposed()

  Returns `true` if the device has been disposed, and `false` otherwise.

  This method gets the dispose state for the device. When a device has been disposed, it is an error to invoke any other method using the device.

  Returns:
    `true` when the device is disposed and `false` otherwise

### release

    protected void release()

  Releases any internal resources back to the operating system and clears all fields except the device handle.

  When a device is destroyed, resources that were acquired on behalf of the programmer need to be returned to the operating system. For example, if the device allocated a font to be used as the system font, this font would be freed in `release`. Also,to assist the garbage collector and minimize the amount of memory that is not reclaimed when the programmer keeps a reference to a disposed device, all fields except the handle are zero'd. The handle is needed by `destroy`.

  This method is called before `destroy`.

  If subclasses reimplement this method, they must call the `super` implementation.

  See Also:
    `dispose()`, `destroy()`

### setWarnings

    public void setWarnings(boolean warnings)

  If the underlying window system supports printing warning messages to the console, setting warnings to `true` prevents these messages from being printed. If the argument is `false` message printing is not blocked.

  Parameters:
    `warnings` - `true`if warnings should be handled, and `false` otherwise
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.