| CATEGORII DOCUMENTE |
| Asp | Autocad | C | Dot net | Excel | Fox pro | Html | Java |
| Linux | Mathcad | Photoshop | Php | Sql | Visual studio | Windows | Xml |
DOCUMENTE SIMILARE |
|||
|
|||
All visual elements of a graphical interface have functionalities in common. Top-level windows, visual controls such as text boxes and push buttons, as well as simple elements for drawing images on the screen have a commonality of capabilities. The Component class, which implements these common functionalities, is an ancestor class for all graphical interface elements.
In the Java system, all classes that implement graphical interface elements are subclasses of the Component class. There are several families of Component class methods, which allow you to control the internal state and on-screen appearance of all Components. They cover the following areas of functionality:
. Component hierarchy. Components are placed on the screen within special Container components. Containers may be placed within other Containers, and so on, forming an on-screen hierarchy of Components.
. Component positioning and sizing.
. Common Component states. All Components share a basic set of internal state variables. The Component class implementation provides methods that allow these state variables to be polled and modified.
. On-screen rendering.
. Delivering and handling events. These include user, custom, and system events such as mouse events, keyboard and keyboard focus events, and so on.
. Preparing and displaying images.
In addition to the Component classes included in the java.awt package, you can create your own custom Components. You can create almost any imaginable visual element as a custom Component. The Project for this chapter demonstrates the creation of a relatively simple custom Component called a Hotspot.
Each Component object instance is "owned by" a parent Component object. The on-screen positioning of a Component is restricted to being within the bounds of its parent Component. More specifically, the rectangle of actual display device pixels, or "bounding rectangle," dedicated to a particular Component is restricted to lying completely within the bounding rectangle of its parent Component. Figure 2-1 illustrates the hierarchy of Components and Container components of a simple graphical user interface. The graphical Component controls are contained within Containers, which are in turn contained within the Frame window, another type of Container component. The Frame window is a top-level window, and so does not have a parent Container.
Figure 2-1 Component hierarchy of a simple dialog box
Components that can contain other Components are derived from the Container class. There are several areas of interest specific to the Container class. This chapter will cover a minority of those topics as necessary to understand the Component class concept.
The getParent method provides a reference to the Container of any Component object:
Container parent = myComponent.getParent();Components that have not been placed within a parent Container, obviously, will not have a parent Container object reference returned by getParent. For orphan Components, as well as for top-level Frame windows, a null will be returned by this method. Components are placed within Containers using the add method of class Container. The specifics of the overloaded versions of this method are discussed in Chapter 3. For simplicity's sake, you can assume that a call to this method effectively sets the owner of the Component object to the specific Container. Listing 2-1 adds a single push button (a type of Component object) to the interface of an Applet (a type of Container object).
Listing 2-1 Adding a Component to a Container using the Container's add method
public class MyApplet extands AppletAll Component objects have a rectangle of display area in which they render themselves. This rectangle is called the Component's bounding rectangle. The size of the Component's bounding rectangle can be looked up using the Component's size method. The resize method allows you to modify these dimensions:
Dimension dimComp = myComponent.size();Note that the actual rectangle of screen real estate a Component is allowed to render itself on is the intersection of the component's bounding rectangle with the parent Container's bounding rectangle (which is intersected with its parent's bounding rectangle, and so on). Therefore, if a Component has been resized to be larger in dimension than its parent Container, then the Component will be "clipped" on the screen according to its position relative to its parent Container.
For the most part, the positioning of a Component object within its parent Container is under the control of the Container's LayoutManager object. Chapter 3 discusses how Components are laid out within a Container by the LayoutManager object. A Component object is positioned relative to the upper-left corner of its parent Container. The location method returns the coordinates of a Component relative to the upper-left corner of its parent Container. That is, the upper-left corner of the parent Container is (0,0) for all Component positioning coordinates. The move method is called to change the position of a Component relative to its parent Container:
// Move myComponent 10 pixels right and down.A Component's bounding rectangle can be fully described by its position and dimensions. The bounds method returns a Rectangle object whose x and y members indicate the position of the Component, and whose width and height members describe the dimensions of the bounding rectangle. The reshape method allows you to modify both the position and dimensions of a Component's bounding rectangle. Listing 2-2 demonstrates the positioning methods for Components. It centers a Component relative to its parent Container's bounding rectangle.
Listing 2-2 Centering a Component with respect to its parent's bounding rectangle
Component comp;All basic visual elements such as push buttons, list boxes, and check boxes can either be enabled or disabled. By default, Components are enabled, though they may be disabled. Disabled Components generally take on a "hampered mode" look and feel, and are generally unreactive to user actions like mouse clicks or keyboard input. Figure 2-2 illustrates several basic visual elements when enabled and disabled. The disable method disables a Component object, and enable forces a Component to be enabled. The isEnabled method returns a boolean true or false, indicating whether the Component is currently enabled.
Figure 2-2 Enabled and disabled Button, List, and Choice
objects
Components can also be hidden or visible. By default, Components when created are visible, but they can be hidden using hide. A hidden Component is effectively removed from the visual interface, as are all of that object's child Components. The Component positioning and other internal state member methods act exactly the same for a Component whether the Component is hidden or visible. The show method forces a Component to be visible. The Component's isVisible method returns a boolean true or false, indicating whether the Component is currently visible. Hiding a Component can be an effective method for removing inappropriate visual elements from the graphical interface.
The isShowing method tells you whether or not a Component has any display surface real estate assigned to it. That is, isShowing returns true only if the Component is visible, and is positioned such that its bounding rectangle intersected with its parent's bounding rectangle is non-null.
A Component can also be marked as valid or invalid. The state of the validation flag indicates whether or not the Component must be laid out using the Component's layout method. The default implementation of this method actually does nothing. However, the Container class overrides the layout method to actually arrange any child Components on the screen.
Use the invalidate method to mark the Component as invalid. The validate method will call layout if the state of the Component is invalid (i.e., invalidate was called prior to the call to validate). If the Component has not been marked as invalid, then validate returns without doing anything.
All the basic visual Components, such as list boxes and push buttons, are able to render themselves on the screen. You can also create custom controls such as gas gauges, spin dials, or just about any visual element imaginable. The SuperBible project for this chapter illustrates the creation of just such a custom control. Your custom controls, however, must render themselves. To actually render custom controls you must re-implement one or more Component class methods.
The central method used to render a Component on the screen is paint. The paint method is passed a Graphics object attached to the display device, and clipped to the bounding rectangle of the Component. (Chapter 1, Applets and Graphics, discussed the Graphics class in detail and how Graphics objects are used to paint on a drawing surface.) The simplest custom Component classes re-implement this method to render the Component in the graphical interface. Listing 2-3 shows a trivial custom paint method implementation that simply draws a filled oval within the Component's bounding rectangle.
Listing 2-3 A simple custom Component
class MyComponent extends CanvasNote that the custom Component class MyComponent actually is derived from the Canvas class. You cannot derive a class from the Component class directly, since the Component class has no public constructors. Generally, you will create custom Component classes, which are derived from the Canvas class, since the Canvas class is the simplest Component with a public constructor.
The Java system calls a Component's paint method asynchronously whenever it determines a Component object must be re-drawn on the display surface. This call is performed by a Thread created and controlled by the Java system. The Java system manages the Graphics object passed to paint directly because graphical device contexts are a limited resource in most graphical operating systems. You must not call paint directly. To force a repainting of a Component object, use the Component's repaint method. Using this method, you can schedule a repainting of the Component within a specific time period, and you can also restrict the repainting to a subset of the the Component's full bounding rectangle. There are four overloaded versions of the repaint method:
repaint();The two versions, which do not specify a time limit, instruct the Java runtime system to schedule a repainting of the Component at some time in the future. The Java system may not schedule a repainting for ten minutes, or the repainting could happen instantaneously. Repainting is a relatively low-priority operation, so the system waits until there is a lull in processing to actually perform the repainting. Using one of the two versions of the repaint method that take a lMillisecs parameter, you can specify a maximum number of milliseconds the Java system can wait before forcing a repainting of your Component object.
The repaint method instructs the Java runtime system to schedule an asynchronous call to Component.update. The update method is responsible for calling paint. The default implementation of update erases the entire drawing surface of the Component object using the Component's background Color, then selects the Component's foreground Color into the Graphics object before calling paint. Figure 2-3 illustrates how Component rendering is accomplished through the three cooperating methods: paint, repaint, and update. You can see that the only method a custom Component needs to re-implement is paint. Re-implementing the update method can be quite useful, especially when animation techniques are used. A discussion of animation techniques and the update method is included in Chapter 1.
Figure 2-3 Cooperative methods paint, repaint, and update
used to keep on-screen rendering of a Component up-to-date
An event, in Java lingo, is an object that describes some specific occurrence in the system. For example, there are several types of mouse events to describe a user's mouse actions. There are also several types of keyboard events to describe user keyboard interactions. Event objects are created by the Java runtime system whenever a specific occurrence is detected, and these Event objects are delivered to specific Components through the Component class Event delivery and handling methods.
The Component class Event delivery methods implement a system whereby Events are passed from a Component to its parent Container, to that object's parent Container, and so on until the event is "handled."
The delivery system can best be illustrated through an example. Figure 2-4 is a screenshot of a very simple user interface in an Applet run within the JDK's AppletViewer. This interface is comprised of the Applet object itself, and a Button object with the caption OK. Imagine the user clicks on the OK Button. This causes an Event object of type ACTION_EVENT to be generated by the Java system and delivered to the OK Button. Button objects, by default implementation, do not handle this type of Event, and so the Event is further delivered to the Button's Container-the Applet object. The Applet object may or may not handle this Event. If not, the Event will further be delivered to the Applet's Container, and so on until either the Event is handled or a top-level Container is reached.
Figure 2-4 A very simple Applet interface
Delivering an Event to a Component is done using the Component's postEvent method. The Java runtime system delivers mouse, keyboard, or other Events to a specific Component using this method.
You can also create your own custom Events (objects derived from the Event class) and deliver them to Components using a similar mechanism. Instead of calling the postEvent method directly, call Component.deliverEvent. The default implementation of deliverEvent takes the Event and passes it to postEvent. Thus, the deafult implementation of deliverEvent is a simple wrapper for postEvent.
The postEvent method is responsible for finding an object to handle each Event it is passed. postEvent offers the Event to three different objects. If no object handles the Event, postEvent returns benignly and the Event is forgotten. The three objects postEvent offers each event to are (in order)
. The Component's peer, through peer.handleEvent
. The Component itself, through this.handleEvent
. The Component's parent Container, through parent.postEvent
The handleEvent method returns a boolean true or false value, indicating whether or not the Event was handled. This pseudo-code in Listing 2-4 illustrates the simple algorithm used by postEvent to find an object to handle each event passed to a particular Component.
Listing 2-4 Pseudo-code for postEvent
boolean method postEvent(Event evt):The default implementation of handleEvent is a giant switch statement. Each Event is classified according to the type of Event, and an appropriate Component class handling method is called. For example, the Component class method mouseDown is called by the default implementation of handleEvent whenever a MOUSE_DOWN Event occurs. The summary section on the next page details all the Component class Event handling methods. Custom Component implementations should override these methods to handle specific types of Events.
Before an Image object can be rendered onto any drawing surface, a representation of the Image suitable for painting on that surface must be constructed by the Java system. The construction is an asynchronous process carried out by the Java system because this process may include downloading of Image data from a remote server. (Downloading of any kind of data is always an asynchronous operation.) The Component class includes methods to manage the Image construction process so that any Component object may prepare and display Images.
The Image construction process is started by a call to the Component's prepareImage method. The Image object to prepare is passed as a parameter to this function. To receive asynchronous notification of the progress of Image construction, an object must implement a special interface called java.awt.image.ImageObserver. The ImageObserver's imageUpdate method, the only method defined by the ImageObserver interface, is called by the Java system automatically as the Image object construction process proceeds.
An implementation of imageUpdate is included in the Component class, so any Component object may be used as an ImageObserver. The default implementation of this method schedules an asynchronous repainting of the Component when the Image has been prepared sufficiently to display. The code snippet in Listing 2-5 illustrates how any Component can prepare an Image for display.
Listing 2-5 Preparing an Image for display
class MyComponent extends ComponentTable 2-1 lists all the methods of the Component class, and provides a brief description of each. The methods are broken down by functional grouping rather than alphabetically.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Component
Purpose
Abstracts all window components. Functionalities common to all such components are implemented in the Component class.
Syntax
public abstract class Component implements ImageObserver;
Description
An abstract windowing component. All Components have a bounding rectangle of on-screen space in which to render themselves. Java has several predefined Component classes, such as a TextField, a Checkbox, or a Frame. The Component class implements methods for Event handling and management of an on-screen bounding rectangle. Figure 2-5 is an inheritance diagram for the Component class.
Figure 2-5 Inheritance diagram of the Component class
PackageName
java.awt
Imports
java.io.PrintStream,java.awt.peer.ComponentPeer, java.awt.image.ImageObserver, java.awt.image.ImageProducer,
java.awt.image.ColorModel
Constructors
None.
Parameters
None.
action
ClassName
Component
Purpose
Event handler for ACTION_EVENT Events.
Syntax
public boolean action(Event evt, Object arg);
Parameters
Event evt
The ACTION_EVENT Event object.
Object arg
Argument attached to the Event object evt. This is identical to the arg member of evt.
Description
Called by the default implementation of handleEvent whenever an ACTION_EVENT is sent to the Component object. Action events include selection of a menu item and pressing a button. Override the default implementation of this method to make your Component react to action events.
Imports
None.
Returns
Returns true if the action event is handled by this Component object. A return value of false causes the Event to be automatically sent to the parent Container of this Component. The default implementation simply returns false.
See Also
The handleEvent method of the Component class
Example
The following example alternatively disables and enables a Go button whenever the Example button is pressed. The action method's arg in this case is the String title of the button that was pressed.
public class MyContainer extends Panelbounds
ClassName
Component
Purpose
Gets the bounding rectangle for this Component.
Syntax
public Rectangle bounds();
Parameters
None.
Description
This method gets a Rectangle object whose x and y members are set to the coordinates of the upper-left corner of the Component, relative to the origin of the parent Container. The width and height members of the Rectangle are set to the dimensions of the Component.
Imports
None.
Returns
A Rectangle object describing the bounding rectangle of this Component object is returned. The values expressed are relative to the origin of the parent Container object. The x and y members describe the upper-left corner of the Component.
See Also
The java.awt.Rectangle class
Example
The following example calculates and writes out the exact coordinates of the lower-right corner of the Component rectangle.
public class MyComponent extends ComponentcheckImage
ClassName
Component
Purpose
To check the status of construction of an Image.
Syntax
public int checkImage(Image img, ImageObserver observer); public int checkImage(Image img, int width, int height, ImageObserver observer);
Parameters
Image img
The Image object whose status is to be checked.
int width
The scaled size of the image representation being checked.
int height
ImageObserver observer
An ImageObserver object currently being notified of the progress of construction of the Image object.
Description
Checks the status of the construction of an Image object. The second overloaded version of this method checks the construction of a scaled representation of the Image object.
Imports
None.
Returns
A logical ORing of the ImageObserver flags indicating what information about the Image is available. This can include one or more of the following ImageObserver values: WIDTH, HEIGHT, PROPERTIES, SOMEBITS, FRAMEBITS, ALLBITS, ERROR.
See Also
The ImageObserver interface
Example
This example prevents the Component from painting its surface until the Image construction flag ALLBITS has been passed to the ImageObserver watching the image construction process.
public MyComponent extends CanvascreateImage
ClassName
Component
Purpose
Creates an in-memory Image with a specified width and height, or from the output of an ImageProducer object.
Syntax
public Image createImage(int x, int y); public Image createImage(ImageProducer producer);
Parameters
int x
The width and height of the resultant Image object.
int y
ImageProducer producer
The ImageProducer object which will provide the data that defines the resultant Image.
Description
Creates an Image object of the specified width and height. This Image is suitable for drawing on for double-buffered screen updating. (See Chapter 1's discussion of double-buffered updating.) The resultant Image will have a compatible ColorModel to the display device associated with this Component object. The second overloaded version of this method creates the Image using data from the ImageProducer.
Imports
java.awt.image.ImageProducer
Returns
An Image object. The Image has not been constructed yet. Use Component.prepareImage() to begin construction of a screen representation of the Image.
See Also
The ImageProducer class
Example
This example creates an in-memory Image, draws on it, and then renders the entire in-memory Image to the Component's display surface.
public void paint(Graphics g)deliverEvent
ClassName
Component
Purpose
Called within your Java code to deliver an Event to any Component object. The Java system uses a different mechanism to deliver user-generated Events.
Syntax
public void deliverEvent(Event evt);
Parameters
Event evt
The Event object to deliver to this Component.
Description
Delivers an Event object to this Component. The default implementation simply calls postEvent. To send a custom Event to a Component object, use the Component's deliverEvent method. This ensures the Event will automatically be routed to the Component's Container if the Component does not handle the Event. The Java system uses a different mechanism to deliver user-generated Events to a Component. That mechanism involves calling the Component's postEvent method directly using a special callback Thread, without using deliverEvent.
Imports
java.awt.Event
Returns
None.
See Also
The Event class
Example
This example delivers a custom Event object to a Component. The Component has been given a custom handleEvent to handle the custom Event type.
public class MyEvent extends Eventdisable
ClassName
Component
Purpose
Disables a Component, which prevents delivery of user-interaction Events to the Component.
Syntax
public void disable();
Parameters
None.
Imports
None.
Description
Disables the component. The Component's peer is also disabled as a result of calling this method. Predefined Components, such as Buttons or Labels, take on a grayed outlook when they are disabled. All Components, either predefined or custom ones, no longer receive user-interaction events once they are disabled.
Returns
None.
Example
See the example for the action method of the Component class.
enable
ClassName
Component
Purpose
Enables or disables the Component.
Syntax
public void enable(); public void enable(boolean fEnabled);
Parameters
boolean fEnabled
If true, the Component is enabled. If false, the Component is disabled.
Imports
None.
Description
Enables the Component. The Component's peer is also enabled as a result of calling this method. The second overloaded version will enable or disable the Component according to the boolean value passed. A disabled Component no longer receives user-generated Events, such as mouse or keyboard Events. Predefined Components, such as Buttons or Labels, take on a grayed out look to denote to the user that they are disabled. Enabled Components receive all user-generated Events.
Returns
None.
Example
See the example for the action method of the Component class.
getBackground
ClassName
Component
Purpose
Gets this Component's current background color.
Syntax
public Color getBackground()
Parameters
None.
Imports
java.awt.Color
Description
Gets the background Color object that is automatically applied to Graphics objects passed to the paint method.
See Also
The Color class; the getForeground, setForeground, and setBackground methods of the Component class
Example
This example code snippet demonstrates the default implementation of the update method of the Component class. The only reference to a Component's background color within the Java API is within update, which uses the background color to erase the Component's entire display surface.
public void update(Graphics g)getColorModel
ClassName
Component
Purpose
Gets the ColorModel for the display surface attached to this Component object.
Syntax
public ColorModel getColorModel();
Imports
java.awt.ColorModel
Description
Gets the ColorModel for the display surface attached to this Component object. A ColorModel provides methods for converting pixel values to red, green, blue, and alpha color component values. In Java 1.0, this method returns an IndexedColorModel, from which you can get the current palette for the system's desktop.
Returns
A ColorModel that encapsulates methods for converting pixel values to red, green,blue, and alpha color components when displayed on the Component's display surface.
See Also
The ColorModel class
Example
This example displays the number of bits/pixel for the Component's display surface.
public MyApplet extends AppletgetFont
ClassName
Component
Purpose
Gets the Font object associated with this Component.
Syntax
public Font getFont();
Imports
java.awt.Font
Description
Gets the Font associated with this Component. You associate a Font with a Component using setFont. Note that the Font returned by getFont may still have to be selected by the Component's Graphics object using Graphics.setFont. For the predefined Component classes in the java.awt package, such as Button and List, it is not necessary for the Graphics object to select the Font. But for custom Components, you will have to add a line like this to your paint method to ensure the Component's Font is selected into the Graphics object:
public void paint(Graphics g)Returns
The Font object currently associated with this Component. If a Font has not been associated with this Component, using setFont will get the parent Container's Font.
See Also
The Font class; the setFont method of the Component class
Example
This example method bolds a Component's Font when called.
public void makeFontBold(Component c)getFontMetrics
ClassName
Component
Purpose
Gets the FontMetrics for a specified Font as it is rendered on the Component's display surface.
Syntax
public FontMetrics getFontMetrics(Font f);
Parameters
Font f
The Font for which to create the FontMetrics.
Imports
java.awt.Font, java.awt.FontMetrics
Description
Gets the FontMetrics for the passed Font. The FontMetrics are for the display surface associated with this Component. You can use the return value from getFont as the Font parameter to this method, like so
FontMetrics fm = getFontMetrics(getFont());See Also
The Font class and the FontMetrics class
Example
This example measures the width in pixels of a given string on the Component's display surface using the Component's Font.
public class MyComponent extends CanvasgetForeground
ClassName
Component
Purpose
Gets the Color used for foreground painting on the Component's display surface in the paint method.
Syntax
public Color getForeground();
Parameters
None.
Imports
java.awt.Color
Description
Gets the foreground Color for this Component. The Foreground color is automatically associated with Graphics objects passed to the paint method by the default implementation of update. See the example of the getBackground method to see how this association happens.
Returns
A Color object representing the current color of the Graphics object passed to paint.
See Also
The Color class; the setForeground method of the Component class
Example
This example sets the foreground and background colors of an in-memory Image object's Graphics to be the same as the component's foreground and background colors.
public class MyComponent extends CanvasgetGraphics
ClassName
Component
Purpose
Gets a Graphics object whose display surface is the rectangle of the on-screen desktop controlled by this Component.
Syntax
public Graphics getGraphics();
Parameters
None.
Imports
java.awt.Graphics
Description
Returns a Graphics object for this Component. If the Component has not been added to a Container using Container.add, this method will return null. The foreground Color, background Color, and Font have been selected by the Graphics object.
Returns
A Graphics object attached to the on-screen rectangle controlled by this Component.
See Also
The Graphics class
Example
See the example for the getForeground method of the Component class.
getParent
ClassName
Component
Purpose
Gets the parent Container of this Component.
Syntax
public Container getParent();
Parameters
None.
Imports
java.awt.Container
Description
Gets the Container for this Component object. If the Component is a top-level Frame window, or the Component has not been added to a Container using Container.add, then this method will return null.
Returns
A reference to the Container object which controls this Component. If the Component does not have a parent Container, null will be returned.
See Also
The add method of the Container class
Example
This example places the Component in the lower-right corner of the parent Container's bounding rectangle.
public class MyComponent extends ComponentgetPeer
ClassName
Component
Purpose
Gets the ComponentPeer associated with this Component object. The ComponentPeer is the proxy through which calls to the native windowing system are made.
Syntax
public ComponentPeer getPeer();
Parameters
None.
Imports
java.awt.peer.ComponentPeer
Description
Gets the Peer object associated with this Component. If this Component has no Peer, null will be returned.
Returns
A Reference to the ComponentPeer attached to this Component. If no ComponentPeer exists, as would be the case if the Component has not been added to a Container using Container.add, then null will be returned.
See Also
The ComponentPeer class
Example
This example implements a virtual Component, which is a Component that does not have a peer. Virtual Components are useful because they inherit all the Component bounding rectangle and Event handling methods. Virtual Components can be used to manage overlapping rectangles of on-screen space, especially because sibling virtual Components will not "clip" each other on the desktop.
public class VirtualComponent extends CanvasgetToolkit
ClassName
Component
Purpose
Gets the Toolkit object, which is the proxy for the native windowing system itself.
Syntax
public Toolkit getToolkit()
Imports
java.awt.Toolkit
Description
Gets the Toolkit object for this Java session. The Toolkit is the proxy for the native windowing system on the local computer. Through the Toolkit you can create ComponentPeers and retrieve various windowing system parameters such as the list of available Fonts.
Returns
A reference to the Toolkit associated with this Component.
See Also
The Toolkit class
Example
The Toolkit can be used to download images or audio clips directly. This example uses a Component's Toolkit to download an Image from within a non-Component object.
public class MyClassgotFocus
ClassName
Component
Purpose
Event handler method for GOT_FOCUS Events.
Syntax
public boolean gotFocus(Event evt, Object arg);
Parameters
Event evt
The GOT_FOCUS Event sent to this Component.
Object arg
The argument to the GOT_FOCUS Event. This parameter is identical to the arg member of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a GOT_FOCUS Event is sent to this Component, indicating that this Component has the keyboard focus. The default implementation of the Event handling method simply returns false. Override the default implementation to allow your Component to react when the Component receives the keyboard focus.
Returns
Have your default implementation return true, indicating the GOT_FOCUS Event has been handled. If false is returned, then the Event will be posted to the this Component's parent Container.
Example
This example reports to System.out when the Component receives or loses keyboard focus.
public class MyComponent extends CanvashandleEvent
ClassName
Component
Purpose
Called to allow the Component a chance to handle user-generated or other Events.
Syntax
public boolean handleEvent(Event evt);
Parameters
Event evt
The Event to be handled by this Component.
Imports
java.awt.Event
Description
This method acts as a central clearing house for all events sent to this Component, or unhandled events sent to subcomponents of this object. The default implementation is a large switch() statement which calls more specific methods, such as keyDown(), mouseMove(), gotFocus(), etc. The return value indicates whether the Event has been handled or should be sent to the parent Container.
Returns
A return value of true indicates the Event has been handled. False indicates it has not, and the Event will be sent to the parent Container.
See Also
All of the Event handle methods of the Component class; the Event class
Example
In this example, it is known that the defined class of Components never handles any Events. The default implementation of handleEvent will still run through its long switch statement and attempt to find a handler for the Event. This class is optimized to stop the Java system from performing that unnecessary handleEvent code.
public class MyNoHandlerComponent extends Componenthide
ClassName
Component
Purpose
Makes the Component invisible or "hidden."
Syntax
public void hide();
Parameters
None.
Imports
None.
Description
Hides the Component. Hidden components are not drawn, nor do they take up space on the display surface.
Returns
None.
See Also
The show method of the Component class
Example
This example Panel uses a Label to display a countdown. When the countdown reaches 0, the Label is hidden. Note that this example does not halt its background Thread in its stop() method implementation for purposes of readablility.
public class MyCountDownApplet extends Applet implementsimageUpdate
ClassName
Component
Purpose
This is the only method of the ImageObserver interface. The default implementation repaints the entire Component whenever any progress is made in the construction of an image.
Syntax
public boolean imageUpdate(Image img, int flags, int x, int y, int width, int height);
Parameters
Image img
The Image object to check. If progress on a screen representation of this Image has been made, then the Component will be repainted asynchronously.
int flags
The ImageObserver flags indicating the progress of construction of a screen representation of the Image object. These ImageObserver flags are ORed together.
int x
Indicates the rectangle of the Image for which the flags parameter is valid.
int y
int width
int height
Imports
None.
Description
Causes an asynchonous repainting of the Component if construction of the Image's representation has made progress. The same flags parameter as is returned by checkImage method is passed. Because this method is implemented in the Component class, any Component object may act as an ImageObserver.
Returns
Returns true if further notification of image construction should continue. False causes further notification to be terminated.
See Also
The imageUpdate method of the ImageObserver interface
Example
This example prevents the Component from repainting unless the ALLBIT flag is passed as part of the flags parameter.
public class MyComponent extends Canvasinside
ClassName
Component
Purpose
Checks to see if a particular point lies within this Component's bounding rectangle.
Syntax
public boolean inside(int x, int y);
Parameters
int x
The coordinates of the point to check.
int y
Imports
None.
Description
Checks whether a particular point lies inside or outside the Component's bounding rectangle. The point to check is specified relative to the parent Container's origin (generally its upper-left corner).
Returns
True is returned if the point lies within this Component's bounding rectangle. Otherwise false is returned.
Example
This example method moves the Component's origin to a point if that point does not lie within the Component's bounding rectangle.
public class MyComponent extends Canvasinvalidate
ClassName
Component
Purpose
Marks the Component as invalid. Calls to Component.validate are ignored unless the Component has been marked as invalid.
Syntax
public void invalidate();
Parameters
None.
Imports
None.
Description
Sets an internal boolean variable, indicating the Component must be validated. Use validate to re-validate the Component Container components. In conjunction with a LayoutManager object, use the invalidate/validate methods to layout subcomponents. By default implementation, Component objects do not react to being tagged as invalid.
Returns
None.
See Also
The Container class and the LayoutManager interface
isEnabled
ClassName
Component
Purpose
Tells whether or not the Component is enabled.
Syntax
public boolean isEnabled();
Parameters
None.
Imports
None.
Description
Checks to see if the Component is currently enabled. When created, a Component is enabled. The disable method is used to disable a Component.
Returns
True if the Component is currently enabled. False if it is not.
Example
The paint method of this Component draws differently if the Component is disabled.
public class MyComponent extends Canvas elseisShowing
ClassName
Component
Purpose
Tells whether or not any part of the Component is currently showing on the desktop.
Syntax
public boolean isShowing();
Parameters
None.
Imports
None.
Description
Checks to see whether the Component object is currently showing on the display screen. The Component is not showing if it is currently hidden. It is not showing if its bounding rectangle has a 0 dimension along either axis. It is not showing if the intersection of its bounding rectangle with its parent's bounding rectangle has a 0 dimension along either axis. That is, Component positioned outside the bounds of its parent Container's bounding rectangle.
Returns
True is returned by this method for all Components which currently have some rectangle of screen real estate. False is returned otherwise.
See Also
The hide and show methods of the Component class
Example
This Component is optimized by immediately returning from its paint implementation if it is not currently showing.
public class MyComponent extends CanvasisValid
ClassName
Component
Purpose
Tells whether or not this Component is currently flagged as "nvlaid.
Syntax
public boolean isValid();
Parameters
None.
Imports
None.
Description
Checks to see whether the Component object is currently valid. Each Component has an internal invalid flag. The invalidate method is used to set this flag, and the validate method is used to clear the flag. The default implementation of validate actually does nothing except clear the flag. The Container class, however, uses the invalid flag and the validate method as an indication of when it should rearrange its child Components with the help of its LayoutManager.
Returns
Valid Components return true from calls to this method. Invalid ones return false.
See Also
The invalidate and validate methods of the Component class
isVisible
ClassName
Component
Purpose
Tells whether or not the Component is currently visible.
Syntax
public boolean isVisible();
Parameters
None.
Imports
None.
Description
Checks to see whether the Component object is currently hidden. To hide a Component object, call its hide method. The show method will alternatively make the object unhidden. Components, when created, are not hidden by default.
Returns
If the Component is currently hidden, false is returned. If it is not hidden, true is returned.
Example
This Component object suspends its background processing Thread while it is hidden. This is accomplished by overriding its show method and by implementing the Runnable interface.
public class MyComponent extends Canvas implementskeyDown
ClassName
Component
Purpose
Event handler for KEY_PRESS Events.
Syntax
public boolean keyDown(Event evt, int key);
Parameters
Event evt
The KEY_PRESS or KEY_ACTION Event which was sent to this Component.
int key
The key pressed. Note that the key is also stored in the key member of evt.
Imports
java.awt.Event
Description
This method is called by the the default implementation of handleEvent whenever a KEY_PRESS or KEY_ACTION Event is sent to the Component. The passed parameters indicate the code for the key pressed. A custom implementation should return true if the event is handled by the Component and should not be sent on to the Component's Container.
Returns
The default implementation of this method simply returns false, indicating the Event should be passed on to the parent Container's handleEvent method.
See Also
The Event class; the handleEvent method of the Component class
Example
This example Component changes its background color whenever the spacebar is pressed. The Component is not repainted until a KEY_RELEASE Event is sent to the Component.
public class MyComponent extends CanvaskeyUp
ClassName
Component
Purpose
Event handler for KEY_RELEASE Events.
Syntax
public boolean keyUp(Event evt, int key);
Parameters
Event evt
The KEY_RELEASE or KEY_ACTION_RELEASE Event which was sent to this Component.
int key
The key pressed. Note that the key is also stored in the key member of evt.
Imports
None.
Description
This method is called by the the default implementation of handleEvent whenever a KEY_RELEASE or KEY_ACTION_RELEASE Event is sent to the Component. The passed parameters indicate the code for the key pressed. A custom implementation should return true if the event is handled by the Component and should not be sent on to the Component's Container.
Returns
The default implementation of this method simply returns false, indicating the Event should be passed on to the parent Container's handleEvent method.
See Also
The Event class; the handleEvent method of the Component class
Example
See the example for the keyDown method of the Component class.
layout
ClassName
Component
Purpose
Called by the default implementation of validate if the Component is currently invalid. The default implementation of Component.layout does nothing.
Syntax
public void layout();
Parameters
None.
Imports
None.
Description
Called when invalid Component objects are being validated as part of validate. This method is primarily used to layout child Components in Container objects. The default implementation of Component.layout does nothing. The Container class implementation of layout relies on a LayoutManager object to handle the laying out of child Components.
Returns
None.
See Also
The validate and invalidate methods of the Component class
list
ClassName
Component
Purpose
To display the internal state of the Component to a PrintStream object.
Syntax
public void list();
public void list(PrintStream out);
public void print(PrintStream out, int indent);
Parameters
PrintStream out
The stream to write a textual description of the state of this Component to.
int indent
The number of space characters (ASCII char 32) to prepend to each line of text written to out.
Imports
java.io.PrintStream
Description
Outputs a textual description of the internal state of the Component to a PrintStream. This can be useful for debugging purposes. The first overloaded version of this method writes the listing to System.out, with an indentation of 0. A call to list() (without parameters) is equivalent to System.out.println(this).
See Also
The PrintStream class; the toString method of the Component class
Example
This example Container class method displays the Container's entire subtree of Components by tracing its hierarchy depth-first, indicating depth by indentation on the PrintStream. Output is written to System.out.
public class MyContainer extends Panellocate
ClassName
Component
Purpose
Returns a reference to this Component if the passed point lies within this Component's bounding rectangle.
Syntax
public Component layout(int x, int y);
Parameters
int x
int y
These two parameters describe a point, relative to this Component's origin, to test.
Imports
None.
Description
A hit-test method which checks to see which Component, or subcomponent, contains the point described by the passed x and y parameters. The Container class uses this method to determine which of its child Component's contains a particular point.
Returns
The Component, or subcomponent, that contains the point (x,y). If the point lies outside the bounds of this Component, null is returned. Container.locate() re-implements this method to test all subcomponents.
See Also
The Container class
location
ClassName
Component
Purpose
Gets the location of this Component's origin.
Syntax
public Point location();
Parameters
None.
Imports
None.
Description
Gets the coordinates of the upper-left corner of this Component. The returned Point is relative to the parent Container's origin.
Returns
The coordinates of the upper-left corner of this Component.
See Also
The Point class
lostFocus
ClassName
Component
Purpose
Event handler for LOST_FOCUS Events.
Syntax
public boolean lostFocus(Event evt, Object arg);
Parameters
Event evt
The LOST_FOCUS Event sent to this Component.
Object arg
The argument to the LOST_FOCUS Event. This parameter is identical to the arg member of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a LOST_FOCUS Event is sent to this Component, indicating this Component no longer has the keyboard focus.
Returns
A return value of true indicates the LOST_FOCUS Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The handleEvent method of the Component class
Example
See the example for the gotFocus method of the Component class.
minimumSize
ClassName
Component
Purpose
Allows a Component to tell its parent Container the minimum bounding rectangle it requires.
Syntax
public Dimension minimumSize();
Imports
None.
Description
Returns the minimum sized rectangle of display surface required for this Component to display itself. When the Component's Container lays out its subcomponents, this method is called to establish a minimum amount of screen real estate needed by the Component.
Returns
The returned Dimension object should indicate the minimum required width and height needed for this Component to display itself. The default implementation of Component.minimumSize() returns the minimum size required as indicated by the Component's peer. If no peer exists, the current size of the Component is returned.
See Also
The preferredSize method of the Component class; the LayoutManager interface; the Dimension class
Example
This example custom Component reports that it requires at least a 10 x 10 bounding rectangle, but would prefer a bounding rectangle large enough to display an initializer String.
public class MyComponent extends CanvasmouseDown
ClassName
Component
Purpose
Event handler for MOUSE_DOWN Events.
Syntax
public boolean mouseDown(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_DOWN Event sent to this Component.
int x
int y
The on-screen coordinates where the mouse was clicked. The coordinates are expressed relative to the origin of this Component object. These two parameters are identical to the x and y members of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a MOUSE_DOWN Event is sent to this Component, indicating the user has clicked the mouse inside this Component.
Returns
A return value of true indicates the MOUSE_DOWN Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The handleEvent, mouseUp, and mouseDrag methods of the Component class
Example
This simple example custom Component prints the coordinates of the mouse while the mouse button is down.
public class MyComponent extends Component {mouseDrag
ClassName
Component
Purpose
Event handler for MOUSE_DRAG Events.
Syntax
public boolean mouseDrag(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_DRAG Event sent to this Component.
int x
int y
The coordinates where the mouse was dragged to. These parameters are identical to the x and y members of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a MOUSE_DRAG Event is sent to this Component, indicating that the mouse has been moved while the mouse button is held down.
Returns
A return value of true indicates the MOUSE_DRAG Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The handleEvent, mouseDown, mouseUp, and mouseMove methods of the Component class; the Event class
Example
See the example for the mouseDown method of the Component class.
mouseEnter
ClassName
Component
Purpose
Event handler for MOUSE_ENTER Events.
Syntax
public boolean mouseEnter(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_ENTER Event sent to this Component.
int x
int y
The argument to the GOT_FOCUS Event. This parameter is identical to the arg member of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a MOUSE_ENTER Event is sent to this Component, indicating that the mouse cursor has moved onto this Component's display rectangle. A Component will only receive a single MOUSE_ENTER Event before a subsequent MOUSE_EXIT Event is sent. That is, each call to mouseEnter is matched by exactly one subsequent call to mouseExit.
Returns
A return value of true indicates the MOUSE_ENTER Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The handleEvent and mouseExit methods of the Component class; the Event class
Example
This example component uses the mouseEnter and mouseExit Event handlers to detect when the mouse cursor is over it. When the mouse is over it, the Component exchanges its background and foreground colors compared to when the mouse is not over it.
public class MyComponent extends CanvasmouseExit
ClassName
Component
Purpose
Event handle for MOUSE_EXIT Events.
Syntax
public boolean mouseExit(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_EXIT Event sent to this Component.
int x
int y
The coordinates of the first point outside the Component's bounds that the mouse is moved to after being inside the bounds. Coordinates are relative to the upper-left corner of the Component.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a MOUSE_EXIT Event is sent to this Component, indicating that the mouse cursor has moved out of this Component's display rectangle. A Component will only receive a single MOUSE_ENTER event before a subsequent MOUSE_EXIT event is sent. That is, each single call to mouseEnter is matched by a single subsequent call to mouseExit. MOUSE_EXIT Events are still sent to a Component even if the user is dragging the mouse (that is, moving the mouse while the mouse button is held down).
Returns
A return value of true indicates the MOUSE_EXIT Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The Event class; the handleEvent and mouseEnter methods of the Component class
Example
See the example for the mouseEnter method of the Component class.
The MouseMove method is described at the end of this chapter on page 135.
mouseUp
ClassName
Component
Purpose
Event handler for MOUSE_UP Events.
Syntax
public boolean mouseUp(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_UP Event sent to this Component.
int x
The coordinates of the mouse cursor when the mouse button was released.
int y
These parameters are identical to the x and y members of evt.
Imports
java.awt.Event
Description
This notification method is called by the default implementation of handleEvent when a MOUSE_UP Event is sent to this Component, indicating the user has let go of the mouse button.
Returns
A return value of true indicates the MOUSE_UP Event is handled by this Component. Returning false causes the event to automatically be sent to this Component's parent Container object.
See Also
The Event class; the handleEvent, mouseDown, mouseMove, and mouseDrag methods of the Component class
Example
See the example for the mouseDown method of the Component class.
move
ClassName
Component
Purpose
Moves the entire Component within its parent Container.
Syntax
public void move(int x, int y);
Parameters
int x
int y
The new coordinate of the upper-left corner of the Component object. The coordinates are expressed relative to the upper-left corner of the parent Container.
Imports
None.
Description
Relocates the Component relative to the upper-left corner of the parent Container. The dimensions of the moved Component are preserved.
Returns
None.
See Also
The location method of the Component class
Example
See the example for the inside method of the Component class.
nextFocus
ClassName
Component
Purpose
Moves the keyboard focus to the next Component within the same Container.
Syntax
public void nextFocus();
Parameters
None.
Imports
None.
Description
Calling this method, moves the keyboard focus to the next Component within the same Container that is eligible to receive keyboard focus. Calling this method for a Component which does not currently have keyboard focus is a no-op. Use of the Component.requestFocus method instead of nextFocus is strongly encouraged. See the example of the requestFocus method.
Returns
None.
See Also
The requestFocus, gotFocus, and lostFocus methods of the Component class
paint
ClassName
Component
Purpose
Called whenever the Java system determines the Component must repaint its surface.
Syntax
public void paint(Graphics g);
Parameters
Graphics g
A Graphics object which has been attached to the display surface for the Component, and whose clipping rectangle has been set to whole or part of the Component's bounding rectangle.
Imports
java.awt.Graphics
Description
This method is called whenever the
Component should render itself on the display surface. The Graphics object
passed to this method is attached to the display surface, and is clipped to the
Component's bounding rectangle. Custom Component objects should override this
method. The paint method can be called by Java at any time, such as when your
Java application is covered up by another application running at the same time.
When the other application is removed from on top of your Java application, a
paint call will be issued for all visible Components.
There are no guarantees on the internal state of the Graphics object, except
that the clipping rectangle will be set to a rectangle equal to or contained by
the Component's bounding rectangle. If you do not override the Component's
default update method, then the foreground and background colors are also
guaranteed to be selected in the Graphics object. In general, it is always safe
to select the foreground Color, background Color, Font, and other special
drawing features into the Graphics object, just to be sure that the Graphics'
internal state is as it is expected to be. Use the repaint method to force an
asynchronous paint call to be issued for the Component.
Returns
None.
See Also
The Graphics class; the repaint method of the Component class
Example
This example Component re-implements both the paint and repaint methods. The re-implementation of the repaint method guarantees that the foreground Color and Font are selected into paint's Graphics parameter, and the Component's surface has not been erased at all. Re-implementing the update method, to not erase a Component's surface, is the technique usually used to avoid flicker in graphics-intensive applications.
public class MyComponent extends CanvaspaintAll
ClassName
Component
Purpose
Paints the Component after calling validate.
Syntax
public void paintAll(Graphics g);
Parameters
Graphics g
A Graphics object, which has been attached to the display surface for the Component, and whose clipping rectangle has been set to whole or part of the Component's bounding rectangle.
Imports
java.awt.Graphics
Description
This method paints the Component after calling validate. Note that this method is usually used to force a Container to repaint itself and all its child Components.
Returns
None.
See Also
The Graphics class; the validate method of the Component class
postEvent
ClassName
Component
Purpose
Routes an Event to its handler method.
Syntax
public boolean postEvent(Event evt);
Parameters
Event evt
The Event object being sent to this Component.
Imports
java.awt.Event
Description
This method handles delivering an Event to either a Component's peer, the Component's handleEvent method, or to the Component's parent Container postEvent method (in that order). Note that the Java system calls a Component's postEvent method to deliver all Events to the Component. When delivering your own Events to a Component, use the deliverEvent method. The recursive design of the postEvent method is used to pass unhandled Events up from Component to parent Container to parent Container until some Event handler method returns true. deliverEvent simple calls postEvent. postEvent will actually allow the peer's handleEvent method to have a first shot at the Event. If the peer's handleEvent returns true, indicating the Event has been handled, then the Component's own handleEvent implementation is never called. This is the reason that, say, Scrollbar objects (which are directly derived from Component) cannot handle a MOUSE_DOWN or MOUSE_UP Event. Instead, the Scrollbar's peer handles these types of Events and changes them into SCROLLBAR_* Events to be handled by the Scrollbar. If neither the peer's nor the Component's handleEvent method handles the Event, the parent Container's postEvent method is passed the Event.
Returns
A return value of true indicates the Event has been handled by either the peer, this Component itself, or the Component's parent Container.
See Also
The Event class; the deliverEvent and handleEvent methods in the Component class
Example
Under some circumstances, you may actually want the Component's parent Container to take the first shot at handling the Component's Events. In this example, postEvent is re-implemented to allow the parent Container first shot at all Events.
public class MyComponent extends CanvaspreferredSize
ClassName
Component
Purpose
Allows the Component to tell its parent Container its preferred amount of on-screen real estate.
Syntax
public Dimension preferredSize();
Parameters
None.
Imports
java.awt.Dimension
Description
Returns the preferred size of the rectangle of display surface for this Component to display itself. When the Component's Container lays out its subcomponents, this method is called to establish a preferred amount of screen real estate for the Component. Re-implement this method to request a particular preferred size for your custom Component.
Returns
The returned Dimension object should indicate the preferred width and height for this Component to display itself. The default implementation of preferredSize returns the preferred size as indicated by the Component's peer. If no peer exists, the current size of the Component is returned.
See Also
The Dimension class; the minimumSize method of the Component class
Example
See the example for the minimumSize method of the Component class.
prepareImage
ClassName
Component
Purpose
Kick-starts the Image construction process.
Syntax
public boolean prepareImage(Image img, ImageObserver observer); public boolean prepareImage(Image img, int width, int height, ImageObserver observer);
Parameters
Image img
The Image object to create a screen representation of.
int width
int height
The scaled size of the Image's representation.
ImageObserver observer
The ImageObserver object that receives notification of the asynchronous progress of the construction of the Image's representation.
Imports
java.awt.Image, java.awt.image.ImageObserver
Description
Starts construction of a screen representation of an Image object. The second overloaded version begins construction of a scaled version of the Image. An Image must be constructed before it can be displayed on a Component's surface. Note, that when you use Graphics.drawImage with a reference to an unconstructed Image object, the Image's construction process is automatically started for you. The prepareImage method allows you to start this process before the Image is displayed on any surface.
Returns
True is returned if the representation of the Image object is complete. Otherwise, false is returned and the Image construction process is started.
See Also
The Image class; the ImageObserver interface; the checkImage and updateImage methods of the Component class
Example
See the example for the checkImage method of the Component class.
ClassName
Component
Purpose
To render the Component to a printer device.
Syntax
public void print(Graphics g);
Parameters
Graphics g
A Graphics object that has been attached to a printer device, and whose clipping rectangle has been set to whole or part of the Component's bounding rectangle.
Imports
java.awt.Graphics
Description
This method is called whenever the Component should render itself on a printer device. The Graphics object passed to this method has been attached to a printing device, and it is clipped to the Component's bounding rectangle. The default implementation simply calls paint, using the same Graphics object. Override this method if your custom Component is to be displayed differently when printed compared to on a display device. There are no guarantees on the internal state of the Graphics object, except that the clipping rectangle will be set to a rectangle equal to or contained by the Component's bounding rectangle. It is a good idea to select the foreground Color, background Color, Font, and other special drawing features into the Graphics object to be sure the Graphics' internal state is as it is expected to be. Note that the print method is essentially the same thing as the paint method. The print method is provided for those instances when you need to know that your Component is being rendered to a printer.
Returns
None.
See Also
The Graphics class; the paint method of the Component class
Example
See the example for the paint method. The paint method and the print method are essentially the same thing.
printAll
ClassName
Component
Purpose
Prints the Component after calling validate.
Syntax
public void printAll(Graphics g);
Parameters
Graphics g
A Graphics object that has been attached to a printer device, and whose clipping rectangle has been set to whole or part of the Component's bounding rectangle.
Imports
java.awt.Graphics
Description
This method prints the Component after calling validate. Note that this method is usually used to force a Container to repaint itself and all its child Components.
Returns
None.
See Also
The Graphics class; the validate method of the Component class
repaint
ClassName
Component
Purpose
Requests an asynchronous repainting of the Component.
Syntax
public void repaint();
public void repaint(long lMillisecs);
public void repaint(int x, int y, int width, int height);
public void repaint(long lMillisecs, int x, int y, int width. int height);
Parameters
long lMillisecs
Maximum number of milliseconds to wait before the Component's update method is called.
int x
int y
int width
int height
These four parameters define a rectangle of area that should be repainted.
Description
You call this method at any time to force an asynchronous repainting of the Component. The Java system schedules a repainting of the Component to be completed by a different Thread at a later time. The second and fourth overloaded version of this method specify a maximum amount of time for the system to wait to schedule a repainting of the Component. The third and fourth overloaded versions allow you to specify a subset of the Component's bounding rectangle to repaint. Unless you use one of the overloaded versions of this method, which allows you to specify a maximum time limit, there is no guarantee on the amount of time before a repaint will be performed. If multiple repaint calls are made in quick succession, they will be combined into a single repainting operation. Repainting is achieved by an asynchronous call to update by the Java system.
See Also
The update and paint methods of the Component class
Example
See the example under the mouseDown method of the Component class.
requestFocus
ClassName
Component
Purpose
If possible, gives the input focus to this Component.
Syntax
public void requestFocus();
Parameters
None.
Imports
None.
Description
Makes a request for the keyboard focus to be switched to this Component. This Component will be notified by a call to gotFocus when the keyboard focus has been switched. Note that disabled Components can not gain the keyboard focus.
Returns
None.
See Also
The nextFocus, gotFocus, and lostFocus methods of the Component class
Example
This example Container has two child Components, a text field, and a checkbox. When the checkbox becomes checked, then the text field is enabled and keyboard focus is given to it. When the checkbox becomes unchecked, then the text field becomes disabled and keyboard focus is given to the checkbox.
public class FocusContainerExample extends Panelreshape
ClassName
Component
Purpose
Changes the origin and dimensions of the Component object in one method call.
Syntax
public void reshape(int x, int y, int width, int height);
Parameters
int x
int y
int width
int height
These four parameters describe a new bounding rectangle for the Component. The x and y coordinates are relative to the upper-left corner of the parent Container.
Imports
None.
Description
Modifies the bounding rectangle of the Component. The move and resize methods are actually wrappers around the reshape method. To detect when your (non-Frame) Component object is being resized or moved, re-implement the reshape method to set some detection flag before calling the base implementation, as demonstrated in the example below.
Returns
None.
See Also
The move and resize methods of the Component class
Example
This example Container re-implements reshape so that it can detect when it is being sized below a particular width and change its LayoutManager accordingly.
public class MyContainer extends Panelresize
ClassName
Component
Purpose
Changes the dimensions of this Component.
Syntax
public void resize(int width, int height); public void resize(Dimension dim);
Parameters
int width
int height
The new width and height of the Component.
Dimension dim
The width and height members of this object describe the new width and height of the Component.
Imports
java.awt.Dimension
Description
Modifies the width and height of the bounding rectangle for this Component to be width pixels in width and height pixels in height. Note that the resize method is just a wrapper around the reshape method.
See Also
The Dimension class; the move and reshape methods of the Component class
Example
This example Component resizes itself to always be large enough to display a particular string.
public class MyComponent extends CanvassetBackground
ClassName
Component
Purpose
Sets the background color used to erase the Component when it is rendered.
Syntax
public void setBackground(Color c);
Parameters
Color c
The background color to use when rendering the Component in the future.
Imports
None.
Description
Sets the background Color to use when painting or printing this Component on a drawing surface. The update method uses a Component's background Color to erase the Component's bounding rectangle on the desktop before calling paint. If update is re-implemented so that it does not erase the Component, then the background Color is never used and might as well never be set.
Returns
None.
See Also
The Color class; the update method of the Component class
Example
See the example under the mouseEnter method of the Component class.
setForeground
ClassName
Component
Purpose
Sets the foreground color used for rendering in the paint method.
Syntax
public void setForeground(Color c);
Parameters
Color c
The background color to use when rendering the Component in the future.
Imports
java.awt.Color
Description
Sets the foreground Color to use when painting or printing this Component on a drawing surface. update modifies the foreground Color used by the passed Graphics to be c before passing the Graphics on to paint. Therefore, Components that override the default implementation of update must set the foreground color explicitly in paint or update.
Returns
None.
See Also
The Color class; the getForeground, update, and paint methods in the Component class
Example
See the example under the mouseEnter method of the Component class.
show
ClassName
Component
Purpose
Makes the Component either hidden or unhidden, according to the parameters passed.
Syntax
public void show(); public void show(boolean fShow);
Parameters
boolean fShow
True if the Component should be unhidden. False if it should be hidden.
Imports
None.
Description
Shows the Component. Hidden components are not drawn, nor do they take up space on the display surface. The second overloaded version allows you to hide or show the Component based on the value of fShow.
Returns
None.
See Also
The hide method of the Component class
Example
This example Component gets hidden whenever it is disabled.
public class MyComponent extends Canvassize
ClassName
Component
Purpose
Gets the dimensions of this Component object.
Syntax
public Dimension size();
Parameters
None.
Imports
None.
Description
Gets the width and height of this Component.
Returns
A Dimension object whose width and height public member variables contain the Component width and height in pixels, respectively.
See Also
The bounds method of the Component class
Example
See the examples under the methods resize, getParent, and getForeground of the Component class.
toString
ClassName
Component
Purpose
Creates a descriptive string detailing the internal state of the Component.
Syntax
public String toString();
Parameters
None.
Imports
None.
Description
Gets a String containing a textual description of this Component object. The resultant String is a concatenation of the object's class, and certain information about the Component's internal state such as whether or not it is enabled or hidden.
Returns
A textual description in a String object.
See Also
The toString method of the Object class
update
ClassName
Component
Purpose
Called by the Java system whenever the Component should repaint itself.
Syntax
public void update(Graphics g);
Parameters
Graphics g
A Graphics object attached to the Component's display device, with a clipping rectangle equal to or a subset of the Component's bounding rectangle.
Imports
java.awt.Graphics
Description
Called automatically by the system when it is time to render the Component on a drawing surface. Calls to repaint cause an asynchronous call to update to be made by a separate Thread. The default implementation of update passes the Graphics object on to paint after erasing the entire drawing surface with the background color and selecting the foreground color into the Graphics object. Many Components, which require a lot of graphical updating, override update so that the entire drawing surface will not be erased. This prevents the Component from appearing to flicker with each graphical update.
See Also
The Graphics class; the paint method of the Component class
Example
See the example for the paint method of the Component class.
validate
ClassName
Component
Purpose
To clear the invalid flag of this Component.
Syntax
public void validate();
Parameters
None.
Imports
None.
Description
Forces the Component to validate itself. When created, Components are marked as valid. Subsequent calls to the invalidate method mark the Component as invalid. Invalid Components validate themselves by calling the layout method before clearing their internal invalid flag. The default implementation of layout does nothing. The invalidate/validate methods are used mostly by Containers to force subcomponents to be laid out by a LayoutManager object.
Returns
None.
See Also
The invalidate and layout methods of the Component class; the layout method of the Container class
The Component Project illustrates the construction of a simple custom Component class: the Hotspot class. The Hotspot class is a Component that has two Images associated with it: an ActiveImage and an InactiveImage. The behavior of a Hotspot object is to display the ActiveImage when the mouse cursor is moved on to the Hotspot. When the mouse is not over the Hotspot, the InactiveImage is displayed. This is a generic custom Component suitable for use in your own Java applications or applets.
This project demonstates several key concepts of Components and custom Components:
. Rendering a custom Component by overriding the Component.paint() method.
. Event handling by implementing Hotspot.mouseEnter() and Hotspot.mouseExit() to make the Hotspot react to user interaction. The Hotspot's Container-the HotsportApplet in this project-can also handle mouse click Events originally delivered to the Hotspot objects.
. Image preparation. The Hotspot implements the ImageObserver interface so that it can be notified of the progress of construction of the on-screen representation of the ActiveImage and the InactiveImage.
Figures 2-6 and 2-7 show the active and inactive images used for one of the Hotspot components in this project.
Figure 2-6 Active image for the first Hotspot component of
the Hotspot project
Figure 2-7 Inactive image for the second Hotspot component of
the Hotspot project
1. Create a file called Hotspot.java using a text editor. This file holds the implementation of the Hotspot custom Component class. Begin by declaring the class and its member variables:
import java.awt.*;3. When the mouse moves over the Hotspot, the active image should be displayed. This is performed by the mouseEnter event handler, which is called automatically whenever a MOUSE_ENTER Event is delivered to the Component. Similarly, when the mouse is no longer over the Component, then the inactive image is displayed. This is performed by the mouseExit Event handler, which is called whenever a MOUSE_EXIT Event is delivered to the Component.
public boolean mouseEnter(Event evt, int x, int y)4. To reduce flicker, prevent default implementation of update from erasing the Component before calling paint.
public void update(Graphics g)5. Painting the Hotspot Component merely involves displaying the Image referred to by _imgCurrent.
public void paint(Graphics g)6. Create a second file named HotspotApplet.java in the same directory. This file holds a sample Applet which displays two Hotspots. The following code initializes and displays two Hotspot Components on the surface of an Applet.
import java.applet.Applet;7. Create a file named Hotspot.html. This is an HTML file with an embedded HotspotApplet in it. Copy the following text to your Hotspot.html file:
<HTML>8. Compile HotspotApplet.java using the JDK's javac compiler. From the directory where your .JAVA and .HTML files are located, run this command:
> javac HotspotApplet.java9. Create four .GIF files to act as your Active and Inactive images. The images displayed above can be used. They are located on the Java API SuperBible CD under the directory FOOBLAHWHATEVER. Copy these four files to the same directory your .JAVA and .HTML files are in. Make sure the names of these four files are "active1.gif", "active2.gif", "inactive1.gif" and "inactive2.gif", respectively.
10. Load the HotspotApplet into the JDK's AppletViewer. From the same directory where your project files are, type this command:
> appletviewer Hotspot.htmlThe Hotspot class maintains an internal reference to two Image objects. The Hotspot._imgActive member variable is a reference to an Image to display when the mouse cursor is over the Hotspot component. The Hotspot._imgInactive member variable is a reference to an Image to display when the mouse cursor is not over the Hotspot. The Hotspot._imgCurrent member variable is a reference to the Image to display: either the active or the inactive Image.
The Hotspot constructor requires references to the active and inactive Image as parameters. Part of object construction includes kick-starting construction of on-screen representation of both these Images using Component.prepareImage(). Always, before an Image can be drawn on a display device, the Image must be prepared by the Java system for rendering on the display device. The Hotspot object uses its inherited implementation of the ImageObserver interface, which is implemented by the Component class. The Component class' implementation of this interface causes the Component to transparently schedule a full repainting of the Hotspot component once the Image has been prepared.
The value of _imgCurrent changes whenever the mouse cursor either enters or exits the bounding rectangle of the Hotspot. Overriding implementations of the mouseEnter and mouseExit Event handling methods are used to detect the position of the mouse cursor. Through the Event delivery methods, the Java system calls a Component's mouseEnter() method exactly once, when the mouse is moved from outside the Hotspot's bounding rectangle to within it. When the mouse cursor is moved from inside to outside the Hotspot's bounding rectangle, the mouseExit method is also called exactly once. Each Hotspot implementation of these methods performs three important tasks:
. Modifies the value of _imgCurrent to indicate either the active or inactive Image.
. Schedules a repainting of the Hotspot using the parameterless repaint() method.
. Returns true from the Event handling method, indicating that the Event has been handled and can be discarded.
Hotspot.paint() is implemented to paint the Hotspot's display surface with the Image indicated by Hotspot._imgCurrent. Before this can be done, the Hotspot must make sure the Image has been fully prepared for display on the device. checkImage() will return a logical ORing of the ImageObserver flags indicating which data for the Image has been successfully prepared for rendering. Hotspot checks for the ALLBITS flag, which indicates the Image has been fully prepared. Once this flag is detected, the Hotspot draws the Image.
Figure 2-8 is a screenshot of the the HotspotApplet running within the JDK's AppletViewer. Note that the mouse cursor is over the first of the two Hotspot Components, so the first Hotspot is displaying its Active image, while the second Hotspot is displaying its Inactive image.
Figure 2-8 Screenshot of the HotspotApplet running within the
JDK's AppletViewer
mouseMove
ClassName
Component
Purpose
The Event handler for MOUSE_MOVE Events.
Syntax
public boolean mouseMove(Event evt, int x, int y);
Parameters
Event evt
The MOUSE_MOVE Event object that was passed to this Component's handleEvent method.
int x
int y
The x and y coordinates, relative to the Component's origin, where the mouse cursor was moved to.
Description
The mouseMove method is called by the default implementation of the handleEvent method of the Component class whenever a MOUSE_MOVE Event is passed to that method. By handling MOUSE_MOVE Events in the mouseMove method, your Component can detect where the mouse cursor is currently positioned within the Component. The first MOUSE_MOVE Event is passed to your Component only after a MOUSE_ENTER Event (MOUSE_ENTER Events can be handled by the mouseEnter Event handler). The MOUSE_EXIT Event, handled by the mouseExit Component method, indicates that the mouse cursor has left your Component's bounding rectangle on the desktop, and that you will no longer receive MOUSE_MOVE Events. If the mouse is being moved with the mouse button held down, then your Component will receive MOUSE_DRAG Events, handled by the mouseDrag Event handler method.
Returns
As with all Event handlers, your implementation of this method should return true if the Event is completely handled by your code. A return value of false will cause the Event to be passed on to your Component's Container through the Event passing mechanism described earlier in this chapter.
See Also
See the mouseDrag, mouseEnter, and mouseExit methods of the Component class.
Example
This example demonstrates simple handling of MOUSE_MOUSE Events using a mouseMove method implementation. The method just writes the mouse position to System.out.
public class MyComponent extends Canvas|
Politica de confidentialitate | Termeni si conditii de utilizare |
Vizualizari: 805
Importanta: 
Termeni si conditii de utilizare | Contact
© SCRIGROUP 2024 . All rights reserved
key in a
dialog. 
key in a
dialog.