Class Window
A Window object is a top-level window with no borders and no menubar. The default layout for a window is BorderLayout .
A window must have either a frame, dialog, or another window defined as its owner when it’s constructed.
In a multi-screen environment, you can create a Window on a different screen device by constructing the Window with Window(Window, GraphicsConfiguration) . The GraphicsConfiguration object is one of the GraphicsConfiguration objects of the target screen device.
In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, the bounds of all configurations are relative to the virtual device coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device, negative coordinates are possible, as shown in the following figure.
In such an environment, when calling setLocation , you must pass a virtual coordinate to this method. Similarly, calling getLocationOnScreen on a Window returns virtual device coordinates. Call the getBounds method of a GraphicsConfiguration to find its origin in the virtual coordinate system.
The following code sets the location of a Window at (10, 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration . If the bounds of the GraphicsConfiguration is not taken into account, the Window location would be set at (10, 10) relative to the virtual-coordinate system and would appear on the primary physical screen, which might be different from the physical screen of the specified GraphicsConfiguration .
Window w = new Window(Window owner, GraphicsConfiguration gc); Rectangle bounds = gc.getBounds(); w.setLocation(10 + bounds.x, 10 + bounds.y);
Note: the location and size of top-level windows (including Window s, Frame s, and Dialog s) are under the control of the desktop’s window management system. Calls to setLocation , setSize , and setBounds are requests (not directives) which are forwarded to the window management system. Every effort will be made to honor such requests. However, in some cases the window management system may ignore such requests, or modify the requested geometry in order to place and size the Window in a way that more closely matches the desktop settings.
Visual effects such as halos, shadows, motion effects and animations may be applied to the window by the desktop window management system. These are outside the knowledge and control of the AWT and so for the purposes of this specification are not considered part of the top-level window.
Due to the asynchronous nature of native event handling, the results returned by getBounds , getLocation , getLocationOnScreen , and getSize might not reflect the actual geometry of the Window on screen until the last request has been processed. During the processing of subsequent requests these values might change accordingly while the window management system fulfills the requests.
An application may set the size and location of an invisible Window arbitrarily, but the window management system may subsequently change its size and/or location when the Window is made visible. One or more ComponentEvent s will be generated to indicate the new geometry.
Windows are capable of generating the following WindowEvents: WindowOpened, WindowClosed, WindowGainedFocus, WindowLostFocus.
How to Write a Focus Listener
Focus events are fired whenever a component gains or loses the keyboard focus. This is true whether the change in focus occurs through the mouse, the keyboard, or programmatically. To get familiar with basic focus concepts or to obtain detailed information about focus, see How to Use the Focus Subsystem.
This section explains how to get focus events for a particular component by registering a FocusListener instance on it. To get focus for a window only, implement a WindowFocusListener instance instead. To obtain the focus status of many components, consider implementing a PropertyChangeListener instance on the KeyboardFocusManager class, as described in Tracking Focus Changes to Multiple Components in How to Use the Focus Subsystem.
The following example demonstrates focus events. The window displays a variety of components. A focus listener, registered on each component, reports every focus-gained and focus-lost event. For each event, the other component involved in the focus change, the opposite component, is reported. For example, when the focus goes from a button to a text field, a focus-lost event is fired by the button (with the text field as the opposite component) and then a focus-gained event is fired by the text field (with the button as the opposite component). Focus-lost as well as focus-gained events can be temporary. For example, a temporary focus-lost event occurs when the window loses the focus. A temporary focus-gained event occurs on popup menus.
Running the Example
- Click the Launch button to run FocusEventDemo using Java™ Web Start (download JDK 7 or later). Alternatively, to compile and run the example yourself, consult the example index.
- You will see a «Focus gained: JTextField» message in the text area — its «opposite component» is null, since it is the first component to have the focus.
- Click the label. Nothing happens because the label, by default, cannot get the focus.
- Click the combo box. A focus-lost event is fired by the text field and a focus-gained event by the combo box. The combo box now shows that it has the focus, perhaps with a dotted line around the text — exactly how this is represented is look and feel dependent.
Notice that when the focus changes from one component to another, the first component fires a focus-lost event before the second component fires a focus-gained event. - Select a choice from the combo box’s menu. Click the combo box again. Notice that no focus event is reported. As long as the user manipulates the same component, the focus stays on that component.
- Click the text area where the focus events are printed. Nothing happens because the text area has been rendered unclickable with setRequestFocusEnabled(false) .
- Click the text field to return the focus to the initial component.
- Press Tab on the keyboard. The focus moves to the combo box and skips over the label.
- Press Tab again. The focus moves to the button.
- Click another window so that the FocusEventDemo window loses the focus. A temporary focus-lost event is generated for the button.
- Click the top of the FocusEventDemo window. A focus-gained event is fired by the button.
- Press Tab on the keyboard. The focus moves to the list.
- Press Tab again. The focus moves to the text area.
Notice that even though you are not allowed to click on the text area, you can tab to it. This is so users who use assistive technologies can determine that a component is there and what it contains. The demo disables click-to-focus for the text area, while retaining its tab-to-focus capability, by invoking setRequestFocusEnabled(false) on the text area. The demo could use setFocusable(false) to truly remove the text area from the focus cycle, but that would have the unfortunate effect of making the component unavailable to those who use assistive technologies. - Press Tab again. The focus moves from the list back to the text field. You have just completed a focus cycle. See the introduction in How to Use the Focus Subsystem for a discussion of focus terminology and concepts.
The complete code for this demo is in the FocusEventDemo.java file. The following code snippet represents the focus-event handling mechanism:
public class FocusEventDemo . implements FocusListener . < public FocusEventDemo() < . JTextField textField = new JTextField("A TextField"); textField.addFocusListener(this); . JLabel label = new JLabel("A Label"); label.addFocusListener(this); . JComboBox comboBox = new JComboBox(vector); comboBox.addFocusListener(this); . JButton button = new JButton("A Button"); button.addFocusListener(this); . JList list = new JList(listVector); list.setSelectedIndex(1); //It's easier to see the focus change //if an item is selected. list.addFocusListener(this); JScrollPane listScrollPane = new JScrollPane(list); . //Set up the area that reports focus-gained and focus-lost events. display = new JTextArea(); display.setEditable(false); //The method setRequestFocusEnabled prevents a //component from being clickable, but it can still //get the focus through the keyboard - this ensures //user accessibility. display.setRequestFocusEnabled(false); display.addFocusListener(this); JScrollPane displayScrollPane = new JScrollPane(display); . >. public void focusGained(FocusEvent e) < displayMessage("Focus gained", e); >public void focusLost(FocusEvent e) < displayMessage("Focus lost", e); >void displayMessage(String prefix, FocusEvent e) < display.append(prefix + (e.isTemporary() ? " (temporary):" : ":") + e.getComponent().getClass().getName() + "; Opposite component: " + (e.getOppositeComponent() != null ? e.getOppositeComponent().getClass().getName() : "null") + newline); >. > The Focus Listener API
The corresponding adapter class is FocusAdapter .
| Method | Purpose |
|---|---|
| focusGained(FocusEvent) | Called just after the listened-to component gets the focus. |
| focusLost(FocusEvent) | Called just after the listened-to component loses the focus. |
| Method | Purpose |
|---|---|
| boolean isTemporary() | Returns the true value if a focus-lost or focus-gained event is temporary. |
| Component getComponent() (in java.awt.event.ComponentEvent ) | Returns the component that fired the focus event. |
| Component getOppositeComponent() | Returns the other component involved in the focus change. For a FOCUS_GAINED event, this is the component that lost the focus. For a FOCUS_LOST event, this is the component that gained the focus. If the focus change involves a native application, a Java application in a different VM or context, or no other component, then null is returned. |
Examples that Use Focus Listeners
The following table lists the examples that use focus listeners.
| Example | Where Described | Notes |
|---|---|---|
| FocusEventDemo | This section | Reports all focus events that occur on several components to demonstrate the circumstances under which focus events are fired. |
| TrackFocusDemo | How to Use the Focus Subsystem | The custom component, Picture , implements a focus listener to draw a red border around the component when it is the current focus owner. |
Class Window
A Window object is a top-level window with no borders and no menubar. The default layout for a window is BorderLayout .
A window must have either a frame, dialog, or another window defined as its owner when it’s constructed.
In a multi-screen environment, you can create a Window on a different screen device by constructing the Window with Window(Window, GraphicsConfiguration) . The GraphicsConfiguration object is one of the GraphicsConfiguration objects of the target screen device.
In a virtual device multi-screen environment in which the desktop area could span multiple physical screen devices, the bounds of all configurations are relative to the virtual device coordinate system. The origin of the virtual-coordinate system is at the upper left-hand corner of the primary physical screen. Depending on the location of the primary screen in the virtual device, negative coordinates are possible, as shown in the following figure.
In such an environment, when calling setLocation , you must pass a virtual coordinate to this method. Similarly, calling getLocationOnScreen on a Window returns virtual device coordinates. Call the getBounds method of a GraphicsConfiguration to find its origin in the virtual coordinate system.
The following code sets the location of a Window at (10, 10) relative to the origin of the physical screen of the corresponding GraphicsConfiguration . If the bounds of the GraphicsConfiguration is not taken into account, the Window location would be set at (10, 10) relative to the virtual-coordinate system and would appear on the primary physical screen, which might be different from the physical screen of the specified GraphicsConfiguration .
Window w = new Window(Window owner, GraphicsConfiguration gc); Rectangle bounds = gc.getBounds(); w.setLocation(10 + bounds.x, 10 + bounds.y);
Note: the location and size of top-level windows (including Window s, Frame s, and Dialog s) are under the control of the desktop’s window management system. Calls to setLocation , setSize , and setBounds are requests (not directives) which are forwarded to the window management system. Every effort will be made to honor such requests. However, in some cases the window management system may ignore such requests, or modify the requested geometry in order to place and size the Window in a way that more closely matches the desktop settings.
Visual effects such as halos, shadows, motion effects and animations may be applied to the window by the desktop window management system. These are outside the knowledge and control of the AWT and so for the purposes of this specification are not considered part of the top-level window.
Due to the asynchronous nature of native event handling, the results returned by getBounds , getLocation , getLocationOnScreen , and getSize might not reflect the actual geometry of the Window on screen until the last request has been processed. During the processing of subsequent requests these values might change accordingly while the window management system fulfills the requests.
An application may set the size and location of an invisible Window arbitrarily, but the window management system may subsequently change its size and/or location when the Window is made visible. One or more ComponentEvent s will be generated to indicate the new geometry.
Windows are capable of generating the following WindowEvents: WindowOpened, WindowClosed, WindowGainedFocus, WindowLostFocus.