Toolkit Methods

Constructors

public Toolkit()--cannot be called by user

Because Toolkit is an abstract class, it has no usable constructor. To get a Toolkit object, ask for your environment's default toolkit by calling the static method getDefaultToolkit() or call Component.getToolkit() to get the toolkit of a component. When the actual Toolkit is created for the native environment, the awt package is loaded, the AWT-Win32 and AWT--Callback-Win32 or AWT-Motif and AWT-Input threads (or the appropriate threads for your environment) are created, and the threads go into infinite loops for screen maintenance and event handling.

Pseudo-Constructors

public static synchronized Toolkit getDefaultToolkit ()

The getDefaultToolkit() method returns the system's default Toolkit object. The default Toolkit is identified by the System property awt.toolkit, which defaults to an instance of the sun.awt.motif.MToolkit class. On the Windows NT/95 platforms, this is overridden by the Java environment to be sun.awt.win32.MToolkit (Java1.0) or sun.awt.windows.MToolkit (Java1.1). On the Macintosh platform, this is overridden by the environment to be sun.awt.macos.MToolkit. Most browsers don't let you change the system property awt.toolkit. Since this is a static method, you don't need to have a Toolkit object to call it; just call Toolkit.getDefaultToolkit().

Currently, only one Toolkit can be associated with an environment. You are more than welcome to try to replace the one provided with the JDK. This permits you to create a whole new widget set, outside of Java, while maintaining the standard AWT API.

System information

public abstract ColorModel getColorModel ()

The getColorModel() method returns the current ColorModel used by the system. The default ColorModel is the standard RGB model, with 8 bits for each of red, green, and blue. There are an additional 8 bits for the alpha component, for pixel-level transparency.

public abstract String[] getFontList ()

The getFontList() method returns a String array of the set Java fonts available with this Toolkit. Normally, these fonts will be understood on all the Java platforms. The set provided with Sun's JDK 1.0 (with Netscape Navigator and Internet Explorer, on platforms other than the Macintosh) contains TimesRoman, Dialog, Helvetica, Courier (the only fixed-width font), DialogInput, and ZapfDingbat.

In Java 1.1, getFont() reports all the 1.0 font names. It also reports Serif, which is equivalent to TimesRoman; San Serif, which is equivalent to Helvetica; and Monospaced, which is equivalent to Courier. The names TimesRoman, Helvetica, and Courier are still supported but should be avoided. They have been deprecated and may disappear in a future release. Although the JDK 1.1 reports the existence of the ZapfDingbat font, you can't use it. The characters in this font have been remapped to Unicode characters in the range \u2700 to \u27ff.

public abstract FontMetrics getFontMetrics (Font font)

The getFontMetrics() method returns the FontMetrics for the given Font object. You can use this value to compute how much space would be required to display some text using this font. You can use this version of getFontMetrics() (unlike the similar method in the Graphics class) prior to drawing anything on the screen.

public int getMenuShortcutKeyMask()

The getMenuShortcutKeyMask() method identifies the accelerator key for menu shortcuts for the user's platform. The return value is one of the modifier masks in the Event class, like Event.CTRL_MASK. This method is used internally by the MenuBar class to help in handling menu selection events. See Chapter 10, Would You Like to Choose from the Menu? for more information about dealing with menu accelerators.

public abstract PrintJob getPrintJob (Frame frame, String jobtitle, Properties props)

The getPrintJob() method initiates a print operation, PrintJob, on the user's platform. After getting a PrintJob object, you can use it to print the current graphics context as follows:

// Java 1.1 only
PrintJob p = getToolkit().getPrintJob (aFrame, "hi", aProps);
Graphics pg = p.getGraphics();
printAll (pg);
pg.dispose();
p.end();

With somewhat more work, you can print arbitrary content. See Chapter 17, Printing, for more information about printing. The frame parameter serves as the parent to any print dialog window, jobtitle serves as the identification string in the print queue, and props serves as a means to provide platform-specific properties (default printer, page order, orientation, etc.). If props is (Properties)null, no properties will be used. props is particularly interesting in that it is used both for input and for output. When the environment creates a print dialog, it can read default values for printing options from the properties sheet and use that to initialize the dialog. After getPrintJob() returns, the properties sheet is filled in with the actual printing options that the user requested. You can then use these option settings as the defaults for subsequent print jobs.

The actual property names are Toolkit specific and may be defined by the environment outside of Java. Furthermore, the environment is free to ignore the props parameter altogether; this appears to be the case with Windows NT/95 platforms. (It is difficult to see how Windows NT/95 would use the properties sheet, since these platforms don't even raise the print dialog until you call the method getGraphics().) Table 15.1 shows some of the properties recognized on UNIX platforms; valid property values are shown in a fixed-width font.

public static String getProperty (String key, String defaultValue)

The getProperty() method retrieves the key property from the system's awt.properties file (located in the lib directory under the java.home directory). If key is not a valid property, defaultValue is returned. This file is used to provide localized names for various system resources.

public abstract int getScreenResolution ()

The getScreenResolution() method retrieves the resolution of the screen in dots per inch. The sharper the resolution of the screen, the greater number of dots per inch. Values vary depending on the system and graphics mode. The PrintJob.getPageResolution() method returns similar information for a printed page.

public abstract Dimension getScreenSize ()

The getScreenSize() method retrieves the dimensions of the user's screen in pixels for the current mode. For instance, a VGA system in standard mode will return 640 for the width and 480 for the height. This information is extremely helpful if you wish to manually size or position objects based upon the physical size of the user's screen. The PrintJob.getPageDimension() method returns similar information for a printed page.

public abstract Clipboard getSystemClipboard()

The getSystemClipboard() method returns a reference to the system's clipboard. The clipboard allows your Java programs to use cut and paste operations, either internally or as an interface between your program and objects outside of Java. For instance, the following code copies a String from a Java program to the system's clipboard:

// Java 1.1 only
Clipboard clipboard = getToolkit().getSystemClipboard();
StringSelection ss = new StringSelection("Hello");
clipboard.setContents(ss, this);

Once you have placed the string "Hello" on the clipboard, you can paste it anywhere. The details of Clipboard, StringSelection, and the rest of the java.awt.datatransfer package are described in Chapter 16, Data Transfer.

public final EventQueue getSystemEventQueue()

After checking whether the security manager allows access, this method returns a reference to the system's event queue.

protected abstract EventQueue getSystemEventQueueImpl()

getSystemEventQueueImpl() does the actual work of fetching the event queue. The toolkit provider implements this method; only subclasses of Toolkit can call it.

Images

The Toolkit provides a set of basic methods for working with images. These methods are similar to methods in the Applet class; Toolkit provides its own implementation for use by programs that don't have access to an AppletContext (i.e., applications or applets that are run as applications). Remember that you need an instance of Toolkit before you can call these methods; for example, to get an image, you might call Toolkit.getDefaultToolkit().getImage(`myImage.gif`).

public abstract Image getImage (String filename)

The getImage() method with a String parameter allows applications to get an image from the local filesystem. Its argument is either a relative or absolute filename for an image in a recognized image file format. The method returns immediately; the Image object that it returns is initially empty. When the image is needed, the system attempts to get filename and convert it to an image. To force the file to load immediately or to check for errors while loading, use the MediaTracker class.

This version of getImage() is not usable within browsers since it will throw a security exception because the applet is trying to access the local filesystem.