java.awt Documentation Differences

This file contains all the changes in documentation in the package java.awt as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Thrown when a serious Abstract Window Toolkit error has occurred. @version 1.12 0213 12/0203/0001 @author Arthur van Hoff

The root event class for all AWT events. This class and its subclasses supercede the original java.awt.Event class. Subclasses of this root AWTEvent class defined outside of the java.awt.event package should define event ID values greater than the value defined by RESERVED_ID_MAX.

The event masks defined in this class are needed by Component subclasses which are using Component.enableEvents() to select for event types not selected by registered listeners. If a listener is registered on a component the appropriate event mask is already set internally by the component.

The masks are also used to specify to which types of events an AWTEventListener should listen. The masks are bitwise-ORed together and passed to Toolkit.addAWTEventListener. @see Component#enableEvents @see Toolkit#addAWTEventListener @see java.awt.event.ActionEvent @see java.awt.event.AdjustmentEvent @see java.awt.event.ComponentEvent @see java.awt.event.ContainerEvent @see java.awt.event.FocusEvent @see java.awt.event.InputMethodEvent @see java.awt.event.InvocationEvent @see java.awt.event.ItemEvent @see java.awt.event.HierarchyEvent @see java.awt.event.KeyEvent @see java.awt.event.MouseEvent @see java.awt.event.MouseWheelEvent @see java.awt.event.PaintEvent @see java.awt.event.TextEvent @see java.awt.event.WindowEvent @author Carl Quinn @author Amy Fowler @version 1.38 0248 12/1103/0001 @since 1.1

Returns a string representing the state of this eventEvent. This method is intended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. @return a string representation of this event.

A class which implements efficient and thread-safe multi-cast event dispatching for the AWT events defined in the java.awt.event package. This class will manage an immutable structure consisting of a chain of event listeners and will dispatch events to those listeners. Because the structure is immutable it is safe to use this API to add/remove listeners during the process of an event dispatch operation. An example of how this class could be used to implement a new component which fires "action" events:

 public myComponent extends Component { ActionListener actionListener = null; public synchronized void addActionListener(ActionListener l) { actionListener = AWTEventMulticaster.add(actionListener l); } public synchronized void removeActionListener(ActionListener l) { actionListener = AWTEventMulticaster.remove(actionListener l); } public void processEvent(AWTEvent e) { // when event occurs which causes "action" semantic if (actionListener = null) { actionListener.actionPerformed(new ActionEvent()); } } 

@author John Rose @author Amy Fowler @version 1.25 0231 12/0203/0001 @since 1.1

Signals that an Absract Window Toolkit exception has occurred. @version 1.13 0214 12/0203/0001 @author Arthur van Hoff

This class is for AWT permissions. An AWTPermission contains a target name but no actions list; you either have the named permission or you don't.

The target name is the name of the AWT permission (see below). The naming convention follows the hierarchical property naming convention. Also an asterisk could be used to represent all AWT permissions.

The following table lists all the possible AWTPermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name	What the Permission Allows	Risks of Allowing this Permission
accessClipboard	Posting and retrieval of information to and from the AWT clipboard	This would allow malfeasant code to share potentially sensitive or confidential information.
accessEventQueue	Access to the AWT event queue	After retrieving the AWT event queue malicious code may peek at and even remove existing events from its event queue as well as post bogus events which may purposefully cause the application or applet to misbehave in an insecure manner.
listenToAllAWTEvents	Listen to all AWT events system-wide	After adding an AWT event listener malicious code may scan all AWT events dispatched in the system allowing it to read all user input (such as passwords). Each AWT event listener is called from within the context of that event queue's EventDispatchThread so if the accessEventQueue permission is also enabled malicious code could modify the contents of AWT event queues system-wide causing the application or applet to misbehave in an insecure manner.
showWindowWithoutWarningBanner	Display of a window without also displaying a banner warning that the window was created by an applet	Without this warning an applet may pop up windows without the user knowing that they belong to an applet. Since users may make security-sensitive decisions based on whether or not the window belongs to an applet (entering a username and password into a dialog box for example) disabling this warning banner may allow applets to trick the user into entering such information.
readDisplayPixels	Readback of pixels from the display screen	Interfaces such as the java.awt.Composite interface or the java.awt.Robot class allow arbitrary code to examine pixels on the display enable malicious code to snoop on the activities of the user.
createRobot	Create java.awt.Robot objects	The java.awt.Robot object allows code to generate native-level mouse and keyboard events as well as read the screen. It could allow malicious code to control the system run other programs read the display and deny mouse and keyboard access to the user.
fullScreenExclusive	Enter full-screen exclusive mode	Entering full-screen exclusive mode allows direct access to low-level graphics card memory. This could be used to spoof the system since the program is in direct control of rendering.

@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.18 0221 12/0203/0001 @author Marianne Mueller @author Roland Schemers

Creates a new AWTPermission with the specified name. The name is the symbolic name of the AWTPermission such as "topLevelWindow" "systemClipboard" etc. An asterisk may be used to indicate all AWT permissions. @param name the name of the AWTPermission.

Creates a new AWTPermission object with the specified name. The name is the symbolic name of the AWTPermission and the actions Stringstring is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new Permissionpermission objects. @param name the name of the AWTPermission. @param actions should be null.

An interface for events that know how dispatch themselves. By implementing this interface an event can be placed upon the event queue and its dispatch() method will be called when the event is dispatched using the EventDispatchThread.

This is a very useful mechanism for avoiding deadlocks. If a thread is executing in a critical section (i.e. it has entered one or more monitors) calling other synchronized code may cause deadlocks. To avoid the potential deadlocks an ActiveEvent can be created to run the second section of code at later time. If there is contention on the monitor the second thread will simply block until the first thread has finished its work and exited its monitors.

For security reasons it is often desirable to use an ActiveEvent to avoid calling untrusted code from a critical thread. For instance peer implementations can use this facility to avoid making calls into user code from a system thread. Doing so avoids potential deadlocks and denial-of-service attacks. @author Timothy Prinzing @version 1.9 0210 12/0203/0001 @since 1.2

The interface for objects which have an adjustable numeric value contained within a bounded range of values. @version 1.10 0214 12/0203/0001 @author Amy Fowler @author Tim Prinzing

AddAdds a listener to recievereceive adjustment events when the value of the adjustable object changes. @param l the listener to recievereceive events @see AdjustmentEvent

Gets the block value increment for the adjustable object. @return the block value increment for the adjustable object

Gets the maximum value of the adjustable object. @return the maximum value of the adjustable object

Gets the minimum value of the adjustable object. @return the minimum value of the adjustable object

Gets the orientation of the adjustable object. @return the orientation of the adjustable object; either HORIZONTAL VERTICAL or NO_ORIENTATION

Gets the unit value increment for the adjustable object. @return the unit value increment for the adjustable object

Gets the current value of the adjustable object. @return the current value of the adjustable object

Gets the length of the propertionalproportional indicator. @return the length of the proportional indicator

Sets the length of the proportionlproportional indicator of the adjustable object. @param v the length of the indicator

TheIndicates that the Adjustable has horizontal orientation.

TheIndicates that the Adjustable has vertical orientation.

This AlphaComposite class implements the basic alpha compositing rules for combining source and destination pixels to achieve blending and transparency effects with graphics and images. The rules implemented by this class are a subsetthe set of the Porter-Duff rules described in T. Porter and T. Duff "Compositing Digital Images" SIGGRAPH 84 253-259.

If any input does not have an alpha channel an alpha value of 1.0 which is completely opaque is assumed for all pixels. A constant alpha value can also be specified to be multiplied with the alpha value of the source pixels.

The following abbreviations are used in the description of the rules:

• Cs = one of the color components of the source pixel.
• Cd = one of the color components of the destination pixel.
• As = alpha component of the source pixel.
• Ad = alpha component of the destination pixel.
• Fs = fraction of the source pixel that contributes to the output.
• Fd = fraction of the input destination pixel that contributes to the output.

The color and alpha components produced by the compositing operation are calculated as follows:

 Cd = Cs*Fs + Cd*Fd Ad = As*Fs + Ad*Fd 

where Fs and Fd are specified by each rule. The above equations assume that both source and destination pixels have the color components premultiplied by the alpha component. Similarly the equations expressed in the definitions of compositing rules below assume premultiplied alpha.

For performance reasons it is preferrable that Rasters passed to the compose method of a CompositeContext object created by the AlphaComposite class have premultiplied data. If either source or destination Rasters are not premultiplied however appropriate conversions are performed before and after the compositing operation.

The alpha resulting from the compositing operation is stored in the destination if the destination has an alpha channel. Otherwise the resulting color is divided by the resulting alpha before being stored in the destination and the alpha is discarded. If the alpha value is 0.0 the color values are set to 0.0. @see Composite @see CompositeContext @version 10 Feb 1997

Creates an AlphaComposite object with the specified rule. @param rule the compositing rule @throws IllegalArgumentException if rule is not one of the following: #CLEAR #SRC #DST #SRC_OVER #DST_OVER #SRC_IN #DST_IN #SRC_OUT or #DST_OUT #SRC_ATOP #DST_ATOP or #XOR

The BasicStroke class defines a basic set of rendering attributes for the outlines of graphics primitives which are rendered with a Graphics2D object that has its Stroke attribute set to this BasicStroke. The rendering attributes defined by BasicStroke describe the shape of the mark made by a pen drawn along the outline of a Shape and the decorations applied at the ends and joins of path segments of the Shape. These rendering attributes include:

width

The pen width measured perpendicularly to the pen trajectory.

end caps

The decoration applied to the ends of unclosed subpaths and dash segments. Subpaths that start and end on the same point are still considered unclosed if they do not have a CLOSE segment. See SEG_CLOSE for more information on the CLOSE segment. The three different decorations are: #CAP_BUTT #CAP_ROUND and #CAP_SQUARE

line joins

The decoration applied at the intersection of two path segments and at the intersection of the endpoints of a subpath that is closed using SEG_CLOSE The three different decorations are: #JOIN_BEVEL #JOIN_MITER and #JOIN_ROUND

miter limit

The limit to trim a line join that has a JOIN_MITER decoration. A line join is trimmed when the ratio of miter length to stroke width is greater than the miterlimit value. The miter length is the diagonal length of the miter which is the distance between the inside corner and the outside corner of the intersection. The smaller the angle formed by two line segments the longer the miter length and the sharper the angle of intersection. The default miterlimit value of 10.0f causes all angles less than 11 degrees to be trimmed. Trimming miters converts the decoration of the line join to bevel.

dash attributes

The definition of how to make a dash pattern by alternating between opaque and transparent sections.

All attributes that specify measurements and distances controlling the shape of the returned outline are measured in the same coordinate system as the original unstroked Shape argument. When a Graphics2D object uses a Stroke object to redefine a path during the execution of one of its draw methods the geometry is supplied in its original form before the Graphics2D transform attribute is applied. Therefore attributes such as the pen width are interpreted in the user space coordinate system of the Graphics2D object and are subject to the scaling and shearing effects of the user-space-to-device-space transform in that particular Graphics2D. For example the width of a rendered shape's outline is determined not only by the width attribute of this BasicStroke but also by the transform attribute of the Graphics2D object. Consider this code:

// sets the Graphics2D object's Tranform attribute g2d.scale(10 10); // sets the Graphics2D object's Stroke attribute g2d.setStroke(new BasicStroke(1.5f));

Assuming there are no other scaling transforms added to the Graphics2D object the resulting line will be approximately 15 pixels wide. As the example code demonstrates a floating-point line offers better precision especially when large transforms are used with a Graphics2D object. When a line is diagonal the exact width depends on how the rendering pipeline chooses which pixels to fill as it traces the theoretical widened outline. The choice of which pixels to turn on is affected by the antialiasing attribute because the antialiasing rendering pipeline can choose to color partially-covered pixels.

For more information on the user space coordinate system and the rendering process see the Graphics2D class comments. @see Graphics2D @version 1.37 0212/0903/01 @author Jim Graham

A border layout lays out a container arranging and resizing its components to fit in five regions: north south east west and center. Each region may contain no more than one component and is identified by a corresponding constant: NORTH SOUTH EAST WEST and CENTER. When adding a component to a container with a border layout use one of these five constants for example:

 Panel p = new Panel(); p.setLayout(new BorderLayout()); p.add(new Button("Okay") BorderLayout.SOUTH); 

As a convenience BorderLayout interprets the absence of a string specification the same as the constant CENTER:

 Panel p2 = new Panel(); p2.setLayout(new BorderLayout()); p2.add(new TextArea()); // Same as p.add(new TextArea() BorderLayout.CENTER); 

In addition BorderLayout supports fourthe relative positioning constants BEFORE_FIRSTPAGE_LINESTART AFTERPAGE_LAST_LINEEND BEFORE_LINE_BEGINSSTART and AFTER_LINE_ENDSEND. In a container whose ComponentOrientation is set to ComponentOrientation.LEFT_TO_RIGHT these constants map to NORTH SOUTH WEST and EAST respectively.

MixingFor compatibility with previous releases BorderLayout also includes the two typesrelative positioning ofconstants BEFORE_FIRST_LINE AFTER_LAST_LINE BEFORE_LINE_BEGINS and AFTER_LINE_ENDS. These are equivalent to PAGE_START PAGE_END LINE_START and LINE_END respectively. For consistency with the relative positioning constants used by other components the latter constants are preferred.

Mixing both absolute and relative positioning constants can lead to unpredicable results. If you use both types the relative constants will take precedence. For example if you add components using both the NORTH and BEFORE_FIRSTPAGE_LINESTART constants in a container whose orientation is LEFT_TO_RIGHT only the BEFORE_FIRSTPAGE_LINESTART will be layed out.

NOTE: Currently (in the Java 2 platform v1.2) BorderLayout does not support vertical orientations. The isVertical setting on the container's ComponentOrientation is not respected.

The components are laid out according to their preferred sizes and the constraints of the container's size. The NORTH and SOUTH components may be stretched horizontally; the EAST and WEST components may be stretched vertically; the CENTER component may stretch both horizontally and vertically to fill any space left over.

Here is an example of five buttons in an applet laid out using the BorderLayout layout manager:

The code for this applet is as follows:

---

 import java.awt.*; import java.applet.Applet; public class buttonDir extends Applet { public void init() { setLayout(new BorderLayout()); add(new Button("North") BorderLayout.NORTH); add(new Button("South") BorderLayout.SOUTH); add(new Button("East") BorderLayout.EAST); add(new Button("West") BorderLayout.WEST); add(new Button("Center") BorderLayout.CENTER); } } 

---

@version 1.45 0249 12/0203/0001 @author Arthur van Hoff @see java.awt.Container#add(String Component) @see java.awt.ComponentOrientation @since JDK1.0

The componentSynonym for comes after thePAGE_END. last line of theExists for compatibility with layout'sprevious contentversions. For Western top-to-bottom left-to-rightPAGE_END orientations this is equivalent to SOUTHpreferred. @see java.awt.Component#getComponentOrientationPAGE_END @since 1.2

TheSynonym component goes at the end of the line direction for the layoutLINE_END. For WesternExists top-to-bottomfor left-to-rightcompatibility orientations thiswith previous isversions. equivalentLINE_END to EASTis preferred. @see java.awt.Component#getComponentOrientationLINE_END @since 1.2

The componentSynonym for comes before thePAGE_START. first line of theExists for compatibility with layout'sprevious contentversions. For Western top-to-bottom left-to-rightPAGE_START orientations this is equivalent to NORTHpreferred. @see java.awt.Component#getComponentOrientationPAGE_START @since 1.2

TheSynonym component goes at the beginning of the line direction for the layoutLINE_START. For WesternExists top-to-bottomfor left-to-rightcompatibility orientations thiswith previous isversions. equivalentLINE_START to WESTis preferred. @see java.awt.Component#getComponentOrientationLINE_START @since 1.2

This class creates a labeled button. The application can cause some action to happen when the button is pushed. This image depicts three views of a "Quit" button as it appears under the Solaris operating system:

The first view shows the button as it appears normally. The second view shows the button when it has input focus. Its outline is darkened to let the user know that it is an active object. The third view shows the button when the user clicks the mouse over the button and thus requests that an action be performed.

The gesture of clicking on a button with the mouse is associated with one instance of ActionEvent which is sent out when the mouse is both pressed and released over the button. If an application is interested in knowing when the button has been pressed but not released as a separate gesture it can specialize processMouseEvent or it can register itself as a listener for mouse events by calling addMouseListener. Both of these methods are defined by Component the abstract superclass of all components.

When a button is pressed and released AWT sends an instance of ActionEvent to the button by calling processEvent on the button. The button's processEvent method receives all events for the button; it passes an action event along by calling its own processActionEvent method. The latter method passes the action event on to any action listeners that have registered an interest in action events generated by this button.

If an application wants to perform some action based on a button being pressed and released it should implement ActionListener and register the new listener to receive events from this button by calling the button's addActionListener method. The application can make use of the button's action command as a messaging protocol. @version 1.58 0368 12/1403/0001 @author Sami Shaio @see java.awt.event.ActionEvent @see java.awt.event.ActionListener @see java.awt.Component#processMouseEvent @see java.awt.Component#addMouseListener @since JDK1.0

Constructs a Button with no label. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless

Constructs a Button with the specified label. @param label A string label for the button. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless

Adds the specified action listener to receive action events from this button. Action events occur when a user presses or releases the mouse over this button. If l is null no exception is thrown and no action is performed. @param l the action listener @see java.awt.event.ActionListener#removeActionListener @see #getActionListeners @see java.awt.Button#removeActionListenerevent.ActionListener @since JDK1.1

Gets the AccessibleContext associated with this Button. For buttons the AccessibleContext takes the form of an AccessibleAWTButton. A new AccessibleAWTButton instance is created if necessary. @return an AccessibleAWTButton that serves as the AccessibleContext of this Button @beaninfo expert: true description: The AccessibleContext associated with this Button.

ReturnReturns an array of all the listenersobjects that were addedcurrently registered as toFooListeners the Buttonupon this withButton. addXXXListener()FooListeners where XXX isare registered using the nameaddFooListener ofmethod.

You can specify the listenerType argument. For example to get all ofwith a class literal such as theFooListener.class. ActionListener(s)For forexample theyou can query givena Button b onefor its wouldaction writelisteners with the following code:

 ActionListener[] als = (ActionListener[])(b.getListeners(ActionListener.class)) ;

If no such listenerlisteners exist list exists thenthis method returns an empty array is returned. @param listenerType Typethe type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener @return allan array of theall objects registered as FooListeners on this button or an empty array if no such listeners of the specifiedhave been added type@exception supported byClassCastException if thislistenerType buttondoesn't specify a class or interface that implements java.util.EventListener @see #getActionListeners @since 1.3

Returns the parametera string representing the state of this buttonButton. This stringmethod is usefulintended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. @return the parameter string of this button.

Processes action events occurring on this button by dispatching them to any registered ActionListener objects.

This method is not called unless action events are enabled for this button. Action events are enabled when one of the following occurs:

• An ActionListener object is registered via addActionListener.
• Action events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the action event. @see java.awt.event.ActionListener @see java.awt.Button#addActionListener @see java.awt.Component#enableEvents @since JDK1.1

Processes events on this button. If an event is an instance of ActionEvent this method invokes the processActionEvent method. Otherwise it invokes processEvent on the superclass.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the event. @see java.awt.event.ActionEvent @see java.awt.Button#processActionEvent @since JDK1.1

Removes the specified action listener so that it no longer receives action events from this button. Action events occur when a user presses or releases the mouse over this button. If l is null no exception is thrown and no action is performed. @param l the action listener @see java.awt.event.ActionListener#addActionListener @see #getActionListeners @see java.awt.Button#addActionListenerevent.ActionListener @since JDK1.1

A Canvas component represents a blank rectangular area of the screen onto which the application can draw or from which the application can trap input events from the user.

An application must subclass the Canvas class in order to get useful functionality such as creating a custom component. The paint method must be overridden in order to perform custom graphics on the canvas. @version 1.28 0332 12/1503/0001 @author Sami Shaio @since JDK1.0

ThisPaints method is called to repaint this canvas.

Most applications that subclass Canvas should override this method in order to perform some useful operation. The paint method provided by Canvas redraws this(typically canvas'scustom rectangle inpainting of the background colorcanvas). The graphics context's origin (0default  0)operation is the top-leftsimply corner of thisto clear the canvas. ItsApplications clipping region is the area of the contextthat override this method need not call super.paint(g). @param g the graphicsspecified Graphics context. @see java.awt.#update(Graphics) @see Component#paint(Graphics)

Updates this componentcanvas.

The AWT callsThis themethod updateis methodcalled in response to a call to repaintupdate or paint. You can assume that theThe backgroundcanvas is notfirst cleared. The updatemethod of Component does the following: Clears this component by filling it with the background color. Sets the color of the graphics context to be the foregroundand color of thisthen completely redrawn component.by Callscalling this componentcanvas's paint method to completely redraw this component. Note: The origin of the graphics context itsapplications that override this method should either call super.update(0  0g) coordinate point is the top-left corner of this component. The clipping regionor ofincorporate the graphicsfunctionality context is thedescribed bounding rectangle of this componentabove into their own code. @param g the specified context to use forGraphics updating.context @see java.awt.Component#paint(Graphics) @see java.awt.Component#repaintupdate(Graphics) @since JDK1.0

A CardLayout object is a layout manager for a container. It treats each component in the container as a card. Only one card is visible at a time and the container acts as a stack of cards. The first component added to a CardLayout object is the visible component when the container is first displayed.

The ordering of cards is determined by the container's own internal ordering of its component objects. CardLayout defines a set of methods that allow an application to flip through these cards sequentially or to show a specified card. The CardLayouCardLayout#addLayoutComponent method can be used to associate a string identifier with a given card for fast random access. @version 1.30 0635 12/3003/0001 @author Arthur van Hoff @see java.awt.Container @since JDK1.0

Removes the specified component from the layout. If the card was visible on top the next card underneath it is shown. @param comp the component to be removed. @see java.awt.Container#remove(java.awt.Component) @see java.awt.Container#removeAll()

A check box is a graphical component that can be in either an "on" (true) or "off" (false) state. Clicking on a check box changes its state from "on" to "off " or from "off" to "on."

The following code example creates a set of check boxes in a grid layout:

---

 setLayout(new GridLayout(3 1)); add(new Checkbox("one" null true)); add(new Checkbox("two")); add(new Checkbox("three")); 

---

This image depicts the check boxes and grid layout created by this code example:

The button labeled one is in the "on" state and the other two are in the "off" state. In this example which uses the GridLayout class the states of the three check boxes are set independently.

Alternatively several check boxes can be grouped together under the control of a single object using the CheckboxGroup class. In a check box group at most one button can be in the "on" state at any given time. Clicking on a check box to turn it on forces any other check box in the same group that is on into the "off" state. @version 1.59 0372 12/1403/0001 @author Sami Shaio @see java.awt.GridLayout @see java.awt.CheckboxGroup @since JDK1.0

Creates a check box with no label. The state of this check box is set to "off " and it is not part of any check box group. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless

Creates a check box with the specified label. The state of this check box is set to "off " and it is not part of any check box group. @param label a string label for this check box or null for no label. @exception HeadlessException if GraphicsEnvironment.isHeadless returns true @see java.awt.GraphicsEnvironment#isHeadless

ConstructsCreates a Checkboxcheck box with the specified label set toin the specified statecheck box group and inset to the specified check box groupstate. @param label a string label for this check box or null for no label. @param group a check box group for this check box or null for no group. @param state the initial state of this check box. @exception HeadlessException if GraphicsEnvironment.isHeadless returns true @see java.awt.GraphicsEnvironment#isHeadless @since JDK1.1

Creates a check box with the specified label and sets the specified state. This check box is not part of any check box group. @param label a string label for this check box or null for no label. @param state the initial state of this check box @exception HeadlessException if GraphicsEnvironment.isHeadless returns true @see java.awt.GraphicsEnvironment#isHeadless

CreatesConstructs a check boxCheckbox with the specified label inset to the specified check box groupstate and set toin the specified statecheck box group. @param label a string label for this check box or null for no label. @param state the initial state of this check box. @param group a check box group for this check box or null for no group. @exception HeadlessException if GraphicsEnvironment.isHeadless returns true @see java.awt.GraphicsEnvironment#isHeadless @since JDK1.1

Adds the specified item listener to receive item events from this check box. Item events are sent to listeners in response to user input but not in response to calls to setState(). If l is null no exception is thrown and no action is performed. @param l the item listener @see java.awt.event.ItemEvent#removeItemListener @see #getItemListeners @see #setState @see java.awt.event.ItemListenerItemEvent @see java.awt.Checkbox#removeItemListenerevent.ItemListener @since JDK1.1

Determines this check box's group. @return this check box's group or null if the check box is not part of a check box group. @see java.awt.Checkbox#setCheckboxGroup

Gets the label of this check box. @return the label of this check box or null if this check box has no label. @see java.awt.Checkbox#setLabel

ReturnReturns an array of all the listenersobjects that were addedcurrently registered as toFooListeners the Checkboxupon this withCheckbox. addXXXListener()FooListeners where XXX isare registered using the nameaddFooListener ofmethod.

You can specify the listenerType argument. For example to get all ofwith a class literal such as theFooListener.class. ItemListener(s)For forexample theyou can query givena Checkbox c onefor its woulditem writelisteners with the following code:

 ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class)) ;

If no such listenerlisteners exist list exists thenthis method returns an empty array is returned. @param listenerType Typethe type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener @return allan array of theall objects registered as FooListeners on this checkbox or an empty array if no such listeners of the specifiedhave been added type@exception supported byClassCastException if thislistenerType checkboxdoesn't specify a class or interface that implements java.util.EventListener @see #getItemListeners @since 1.3

Determines whether this check box is in the "on" or "off" state. The boolean value true indicates the "on" state and false indicates the "off" state. @return the state of this check box as a boolean value. @see java.awt.Checkbox#setState

Returns the parametera string representing the state of this check boxCheckbox. This stringmethod is usefulintended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. @return the parameter string of this check box.

Processes events on this check box. If the event is an instance of ItemEvent this method invokes the processItemEvent method. Otherwise it calls its superclass's processEvent method.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the event. @see java.awt.event.ItemEvent @see java.awt.Checkbox#processItemEvent @since JDK1.1

Processes item events occurring on this check box by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:

• An ItemListener object is registered via addItemListener.
• Item events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the item event. @see java.awt.event.ItemEvent @see java.awt.event.ItemListener @see java.awt.Checkbox#addItemListener @see java.awt.Component#enableEvents @since JDK1.1

Removes the specified item listener so that the item listener no longer receives item events from this check box. If l is null no exception is thrown and no action is performed. @param l the item listener @see java.awt.event.ItemEvent#addItemListener @see #getItemListeners @see java.awt.event.ItemListenerItemEvent @see java.awt.Checkbox#addItemListenerevent.ItemListener @since JDK1.1

Sets this check box's group to be the specified check box group. If this check box is already in a different check box group it is first taken out of that group. @param g the new check box group or null to remove this check box from any check box group. @see java.awt.Checkbox#getCheckboxGroup

Sets this check box's label to be the string argument. @param label a string to set as the new label or null for no label. @see java.awt.Checkbox#getLabel

Sets the state of this check box to the specified state. The boolean value true indicates the "on" state and false indicates the "off" state.

Note that this method should be primarily used to initialize the state of the checkbox. Programmatically setting the state of the checkbox will not trigger an ItemEvent. The only way to trigger an ItemEvent is by user interaction. @param state the boolean state of the check box. @see java.awt.Checkbox#getState

The CheckboxGroup class is used to group together a set of Checkbox buttons.

Exactly one check box button in a CheckboxGroup can be in the "on" state at any given time. Pushing any button sets its state to "on" and forces any other button that is in the "on" state into the "off" state.

The following code example produces a new check box group with three check boxes:

---

 setLayout(new GridLayout(3 1)); CheckboxGroup cbg = new CheckboxGroup(); add(new Checkbox("one" cbg true)); add(new Checkbox("two" cbg false)); add(new Checkbox("three" cbg false)); 

---

This image depicts the check box group created by this example:

@version 1.29 0230 12/0203/0001 @author Sami Shaio @see java.awt.Checkbox @since JDK1.0

This class represents a check box that can be included in a menu. ClickingSelecting on the check box in the menu changes its state from "on" to "off" or from "off" to "on."

The following picture depicts a menu which contains an instance of CheckBoxMenuItem:

The item labeled Check shows a check box menu item in its "off" state.

When a check box menu item is selected AWT sends an item event to the item. Since the event is an instance of ItemEvent the processEvent method examines the event and passes it along to processItemEvent. The latter method redirects the event to any ItemListener objects that have registered an interest in item events generated by this menu item. @version 1.49 0362 12/1403/0001 @author Sami Shaio @see java.awt.event.ItemEvent @see java.awt.event.ItemListener @since JDK1.0

Create a check box menu item with an empty label. The item's state is initially set to "off." @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless @since JDK1.1

Create a check box menu item with the specified label. The item's state is initially set to "off." @param label a string label for the check box menu item or null for an unlabeled menu item. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless

Create a check box menu item with the specified label and state. @param label a string label for the check box menu item or null for an unlabeled menu item. @param state the initial state of the menu item where true indicates "on" and false indicates "off." @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.GraphicsEnvironment#isHeadless @since JDK1.1

Adds the specified item listener to receive item events from this check box menu item. Item events are sent in response to user actions but not in response to calls to setState(). If l is null no exception is thrown and no action is performed. @param l the item listener @see java.awt.event.ItemEvent#removeItemListener @see #getItemListeners @see #setState @see java.awt.event.ItemListenerItemEvent @see java.awt.Choice#removeItemListenerevent.ItemListener @since JDK1.1

ReturnReturns an array of all the listenersobjects that were addedcurrently registered as toFooListeners the CheckboxMenuItemupon this withCheckboxMenuItem. addXXXListener()FooListeners where XXX isare registered using the nameaddFooListener ofmethod.

You can specify the listenerType argument. For example to get all ofwith a class literal such as theFooListener.class. ItemListener(s)For forexample theyou can givenquery a CheckboxMenuItem c onefor its item listeners with wouldthe following writecode:

 ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class)) ;

If no such listenerlisteners exist list exists thenthis method returns an empty array is returned. @param listenerType Typethe type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener @return allan array of theall objects registered as FooListeners on this checkbox menuitem or an empty array if no such listeners of the specifiedhave been added type@exception supported byClassCastException if thislistenerType checkboxdoesn't menuspecify itema class or interface that implements java.util.EventListener @see #getItemListeners @since 1.3

Determines whether the state of this check box menu item is "on" or "off." @return the state of this check box menu item where true indicates "on" and false indicates "off." @see java.awt.CheckboxMenuItem#setState

Returns the parametera string representing the state of this check box menu itemCheckBoxMenuItem. This stringmethod is usefulintended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. @return the parameter string of this check box menu item.

Processes events on this check box menu item. If the event is an instance of ItemEvent this method invokes the processItemEvent method. If the event is not an item event it invokes processEvent on the superclass.

Check box menu items currently support only item events.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the event @see java.awt.event.ItemEvent @see java.awt.CheckboxMenuItem#processItemEvent @since JDK1.1

Processes item events occurring on this check box menu item by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this menu item. Item events are enabled when one of the following occurs:

• An ItemListener object is registered via addItemListener.
• Item events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the item event. @see java.awt.event.ItemEvent @see java.awt.event.ItemListener @see java.awt.CheckboxMenuItem#addItemListener @see java.awt.MenuItem#enableEvents @since JDK1.1

Removes the specified item listener so that it no longer receives item events from this check box menu item. If l is null no exception is thrown and no action is performed. @param l the item listener @see java.awt.event.ItemEvent#addItemListener @see #getItemListeners @see java.awt.event.ItemListenerItemEvent @see java.awt.Choice#addItemListenerevent.ItemListener @since JDK1.1

Sets this check box menu item to the specifed state. The boolean value true indicates "on" while false indicates "off." @param

Note bthat this method should be primarily used to initialize the booleanstate of the check box menu item. Programmatically setting the state of thisthe check box menu item will not trigger an ItemEvent. The only way to trigger an ItemEvent is by user interaction. @param b true if the check box menu item is on otherwise false @see java.awt.CheckboxMenuItem#getState

The Choice class presents a pop-up menu of choices. The current choice is displayed as the title of the menu.

The following code example produces a pop-up menu:

---

 Choice ColorChooser = new Choice(); ColorChooser.add("Green"); ColorChooser.add("Red"); ColorChooser.add("Blue"); 

---

After this choice menu has been added to a panel it appears as follows in its normal state:

In the picture "Green" is the current choice. Pushing the mouse button down on the object causes a menu to appear with the current choice highlighted.

Some native platforms do not support arbitrary resizing of Choice components and the behavior of setSize()/getSize() is bound by such limitations. Native GUI Choice components' size are often bound by such attributes as font size and length of items contained within the Choice.

@version 1.64 0378 12/1403/0001 @author Sami Shaio @author Arthur van Hoff @since JDK1.0

Creates a new choice menu. The menu initially has no items in it.

By default the first item added to the choice menu becomes the selected item until a different selection is made by the user by calling one of the select methods. @exception HeadlessException if GraphicsEnvironment.isHeadless() returns true @see java.awt.ChoiceGraphicsEnvironment#isHeadless @see #select(int) @see java.awt.Choice#select(java.lang.String)

Adds an item to this Choice menu. @param item the item to be added @exception NullPointerException if the item's value is null. @since JDK1.1

Obsolete as of Java 2 platform v1.1. Please use the add method instead.

Adds an item to this Choice menu. @param item the item to be added @exception NullPointerException Ifif the item's value is equal to null.

Adds the specified item listener to receive item events from this Choice menu. Item events are sent in response to user input but not in response to calls to select. If l is null no exception is thrown and no action is performed. @param l the item listener. @see java.awt.event.ItemEvent#removeItemListener @see #getItemListeners @see #select @see java.awt.event.ItemListenerItemEvent @see java.awt.Choice#removeItemListenerevent.ItemListener @since JDK1.1

Creates the Choice's peer. This peer allows us to change the look of the Choice without changing its functionality. @see java.awt.Toolkit#createChoice(java.awt.Choice) @see java.awt.Component#getToolkit()

Gets the AccessibleContext associated with this Choice. For Choice components the AccessibleContext takes the form of an AccessibleAWTChoice. A new AccessibleAWTChoice instance is created if necessary. @return an AccessibleAWTChoice that serves as the AccessibleContext of this Choice

Gets the string at the specified index in this Choice menu. @param index the index at which to begin. @see java.awt.Choice#getItemCount

Returns the number of items in this Choice menu. @seereturn java.awt.the number of items in this Choice menu @see #getItem @since JDK1.1

ReturnReturns an array of all the listenersobjects that were addedcurrently registered as toFooListeners the Choiceupon this withChoice. addXXXListener()FooListeners where XXX isare registered using the nameaddFooListener ofmethod.

You can specify the listenerType argument. For example to get all ofwith a class literal such as theFooListener.class. ItemListener(s)For forexample theyou can query givena Choice c onefor its woulditem writelisteners with the following code:

 ItemListener[] ils = (ItemListener[])(c.getListeners(ItemListener.class)) ;

If no such listenerlisteners exist list exists thenthis method returns an empty array is returned. @param listenerType Typethe type of listeners requested; this parameter should specify an interface that descends from java.util.EventListener @return allan array of theall objects registered as FooListeners on this choice or an empty array if no such listeners of the specifiedhave been added type@exception supported byClassCastException if thislistenerType choicedoesn't specify a class or interface that implements java.util.EventListener @see #getItemListeners @since 1.3

Gets a representation of the current choice as a string. @return a string representation of the currently selected item in this choice menu. @see java.awt.Choice#getSelectedIndex

Returns an array (length 1) containing the currently selected item. If this choice has no items returns null. @see ItemSelectable

Inserts the item into this choice at the specified position. Existing items at an index greater than or equal to index are shifted up by one to accommodate the new item. If index is greater than or equal to the number of items in this choice item is added to the end of this choice.

If the item is the first one being added to the choice then the item becomes selected. Otherwise if the selected item was one of the items shifted the first item in the choice becomes the selected item. If the selected item was no among those shifted it remains the selected item. @param item the non-null item to be inserted @param index the position at which the item should be inserted @exception IllegalArgumentException if index is less than 0.

Returns the parametera string representing the state of this choiceChoice menu. This stringmethod is usefulintended to be used only for debugging purposes and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null. @return the parameter string of this Choice menu.

Processes events on this choice. If the event is an instance of ItemEvent it invokes the processItemEvent method. Otherwise it calls its superclass's processEvent method.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the event. @see java.awt.event.ItemEvent @see java.awt.Choice#processItemEvent @since JDK1.1

Processes item events occurring on this Choice menu by dispatching them to any registered ItemListener objects.

This method is not called unless item events are enabled for this component. Item events are enabled when one of the following occurs:

• An ItemListener object is registered via addItemListener.
• Item events are enabled via enableEvents.

Note that if the event parameter is null the behavior is unspecified and may result in an exception. @param e the item event. @see java.awt.event.ItemEvent @see java.awt.event.ItemListener @see java.awt.Choice#addItemListener @see java.awt.Component#enableEvents @since JDK1.1

RemoveRemoves the first occurrence of item from the Choice menu. If the item being removed is the currently selected item then the first item in the choice becomes the selected item. Otherwise the currently selected item remains selected (and the selected index is updated accordingly). @param item the item to remove from this Choice menu. @exception IllegalArgumentException if the item doesn't exist in the choice menu. @since JDK1.1

Removes an item from the choice menu at the specified position. If the item being removed is the currently selected item then the first item in the choice becomes the selected item. Otherwise the currently selected item remains selected (and the selected index is @param position the position of the item. @throws IndexOutOfBoundsException if the specified position is out of bounds @since JDK1.1

Removes all items from the choice menu. @see java.awt.Choice#remove @since JDK1.1

Removes the specified item listener so that it no longer receives item events from this Choice menu. If l is null no exception is thrown and no action is performed. @param l the item listener. @see java.awt.event.ItemEvent#addItemListener @see #getItemListeners @see java.awt.event.ItemListenerItemEvent @see java.awt.Choice#addItemListenerevent.ItemListener @since JDK1.1

Sets the selected item in this Choice menu to be the item whose name is equal to the specified string. If more than one item matches (is equal to) the specified string the one with the smallest index is selected.

Note that this method should be primarily used to initially select an item in this component. Programmatically calling this method will not trigger an ItemEvent. The only way to trigger an ItemEvent is by user interaction. @param str the specified string @see java.awt.Choice#getSelectedItem @see java.awt.Choice#getSelectedIndex

Sets the selected item in this Choice menu to be the item at the specified position.

Note that this method should be primarily used to initially select an item in this component. Programmatically calling this method will not trigger an ItemEvent. The only way to trigger an ItemEvent is by user interaction. @param pos the positon of the selected item. @exception IllegalArgumentException if the specified position is invalid.greater than the number of items or less than zero @see java.awt.Choice#getSelectedItem @see java.awt.Choice#getSelectedIndex

A component is an object having a graphical representation that can be displayed on the screen and that can interact with the user. Examples of components are the buttons checkboxes and scrollbars of a typical graphical user interface.

The Component class is the abstract superclass of the nonmenu-related Abstract Window Toolkit components. Class Component can also be extended directly to create a lightweight component. A lightweight component is a component that is not associated with a native opaque window.

Serialization

It is important to note that only AWT listeners which conform to the Serializable protocol will be saved when the object is stored. If an AWT object has listeners that aren't marked serializable they will be dropped at writeObject time. Developers will need as always to consider the implications of making an object serializable. One situation to watch out for is this:

 import java.awt.*; import java.awt.event.*; import java.io.Serializable; class MyApp implements ActionListener Serializable { BigObjectThatShouldNotBeSerializedWithAButton bigOne; Button aButton = new Button(); MyApp() { // Oops now aButton has a listener with a reference // to bigOne aButton.addActionListener(this); } public void actionPerformed(ActionEvent e) { System.out.println("Hello There"); } } 

In this example serializing aButton by itself will cause MyApp and everything it refers to to be serialized as well. The problem is that the listener is serializable by coincidence not by design. To separate the decisions about MyApp and the ActionListener being serializable one can use a nested class as in the following example:

 import java.awt.*; import java.awt.event.*; import java.io.Serializable; class MyApp java.io.Serializable { BigObjectThatShouldNotBeSerializedWithAButton bigOne; Button aButton = new Button(); class MyActionListener implements ActionListener { public void actionPerformed(ActionEvent e) { System.out.println("Hello There"); } } MyApp() { aButton.addActionListener(new MyActionListener()); } } 

@version 1.265 02330 12/2803/0001 @author Arthur van Hoff @author Sami Shaio

Checks whether the specified point is within this object's bounds where the point's x and y coordinates are defined to be relative to the coordinate system of the object. @param p the Point relative to the coordinate system of the object @return true if object contains Point; otherwise false

Returns the Accessible child if one exists contained at the local coordinate Point. Otherwise returns null. @param p Thethe point defining the top-left corner of the Accessible given in the coordinate space of the object's parent. @return the Accessible if it exists at the specified location; else null

ReturnReturns the nth Accessible child of the object. @param i zero-based index of child @return the nth Accessible child of the object

Returns the number of accessible children in the object. If all of the children of this object implement Accessible thanthen this method should return the number of children of this object. @return the number of accessible children in the object.

GetGets the AccessibleComponent associated with this object if one exists. Otherwise return null. @return the component

GetGets the accessible description of this object. This should be a concise localized description of what this object is - what is its meaning to the user. If the object has a tooltip the tooltip text may be an appropriate string to return assuming it contains a concise description of the object (instead of just the name of the object - e.g. a "Save" icon on a toolbar that had "save" as the tooltip text shouldn't return the tooltip text as the description but something like "Saves the current text document" instead). @return the localized description of the object -- can be null if this object does not have a description @see javax.accessibility.AccessibleContext#setAccessibleDescription

GetGets the index of this object in its accessible parent. @return the index of this object in its parent; or -1 if this object does not have an accessible parent. @see #getAccessibleParent

GetGets the accessible name of this object. This should almost never return java.awt.Component.getName() as that generally isn't a localized name and doesn't have meaning for the user. If the object is fundamentally a text object (e.g. a menu item) the accessible name should be the text of the object (e.g. "save"). If the object has a tooltip the tooltip text may also be an appropriate String to return. @return the localized name of the object -- can be null if this object does not have a name @see javax.accessibility.AccessibleContext#setAccessibleName

GetGets the Accessible parent of this object. If the parent of this object implements Accessible this method should simply return getParent(). @return the Accessible parent of this object -- can be null if this object does not have an Accessible parent

GetGets the role of this object. @return an instance of AccessibleRole describing the role of the object @see javax.accessibility.AccessibleRole

GetGets the state of this object. @return an instance of AccessibleStateSet containing the current state set of the object @see javax.accessibility.AccessibleState

GetGets the background color of this object. @return the background color if supported of the object; otherwise null

Gets the bounds of this object in the form of a Rectangle object. The bounds specify this object's width height and location relative to its parent. @return Aa rectangle indicating this component's bounds; null if this object is not on the screen.

GetGets the Cursor of this object. @return the Cursor if supported of the object; otherwise null

GetGets the Font of this object. @retur