java.awt.Frame Maven / Gradle / Ivy
/*
NOTICE
(c) 2005-2007 Sun Microsystems, Inc. All Rights Reserved.
Neither this file nor any files generated from it describe a complete
specification, and they may only be used as described below. For
example, no permission is given for you to incorporate this file, in
whole or in part, in an implementation of a Java specification.
Sun Microsystems Inc. owns the copyright in this file and it is provided
to you for informative, as opposed to normative, use. The file and any
files generated from it may be used to generate other informative
documentation, such as a unified set of documents of API signatures for
a platform that includes technologies expressed as Java APIs. The file
may also be used to produce "compilation stubs," which allow
applications to be compiled and validated for such platforms.
Any work generated from this file, such as unified javadocs or compiled
stub files, must be accompanied by this notice in its entirety.
This work corresponds to the API signatures of JSR 217: Personal Basis
Profile 1.1. In the event of a discrepency between this work and the
JSR 217 specification, which is available at
http://www.jcp.org/en/jsr/detail?id=217, the latter takes precedence.
*/
package java.awt;
import java.awt.event.*;
// import javax.accessibility.*;
//
// import java.awt.peer.FramePeer;
import java.util.Vector;
import java.io.Serializable;
import java.io.ObjectOutputStream;
import java.io.ObjectInputStream;
import java.io.IOException;
// import sun.awt.AppContext;
import java.lang.ref.WeakReference;
/**
* A Frame is a top-level window with a title and a border.
*
* The size of the frame includes any area designated for the
* border. The dimensions of the border area may be obtained
* using the getInsets method, however, since
* these dimensions are platform-dependent, a valid insets
* value cannot be obtained until the frame is made displayable
* by either calling pack or show.
* Since the border area is included in the overall size of the
* frame, the border effectively obscures a portion of the frame,
* constraining the area available for rendering and/or displaying
* subcomponents to the rectangle which has an upper-left corner
* location of (insets.left, insets.top), and has a size of
* width - (insets.left + insets.right) by
* height - (insets.top + insets.bottom).
*
* The default layout for a frame is BorderLayout.
*
* A frame may have its native decorations (i.e. Frame
* and Titlebar) turned off
* with setUndecorated. This can only be done while the frame
* is not {@link Component#isDisplayable() displayable}.
*
* In a multi-screen environment, you can create a Frame
* on a different screen device by constructing the Frame
* with {@link #Frame(GraphicsConfiguration)} or
* {@link #Frame(String title, 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-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 Frame
* 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 the Frame 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
* Frame 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.
*
*
* Frame f = new Frame(GraphicsConfiguration gc);
* Rectangle bounds = gc.getBounds();
* f.setLocation(10 + bounds.x, 10 + bounds.y);
*
*
*
* Frames are capable of generating the following types of
* WindowEvents:
*
* WINDOW_OPENED
* WINDOW_CLOSING
* WINDOW_CLOSED
* WINDOW_ICONIFIED
* WINDOW_DEICONIFIED
* WINDOW_ACTIVATED
* WINDOW_DEACTIVATED
* WINDOW_GAINED_FOCUS
* WINDOW_LOST_FOCUS
*
*
*
*
*
* Clarifications
*
*
* - The size and location of Frame instances may be severely limited
* in this profile. Please see the note concerning
* size and location of
java.awt.Window.
*
* - Instances of
Frame are initially created in
* "windowed" mode. See:
*
* - {@link GraphicsDevice#setFullScreenWindow(Window)}
*
*
* - The decoration, title, and resizability of a
Frame
* are under the control of the window management system. Method calls
* to change these properties are requests (not directives) which are
* forwarded to the window management system. As a result:
*
*
* - The window management system may ignore the decoration of a Frame
* as reported by {@link #isUndecorated}.
* See:
*
* - {@link #setUndecorated}
*
- {@link #isUndecorated}
*
*
* - The window management system may ignore the title of a Frame
* as reported by {@link #getTitle}.
* See:
*
* - {@link #Frame(String)}
*
- {@link #Frame(String, GraphicsConfiguration)}
*
- {@link #setTitle}
*
- {@link #getTitle}
*
*
* - The window management system may ignore the resizability of a Frame
* as reported by {@link #isResizable}.
* See:
*
* - {@link #isResizable}
*
- {@link #setResizable(boolean)}
*
*
*
*
*
*
* For more information, see
* Profile-specific properties.
*
*
*
* Restrictions
*
*
* - Only a single instance of
Frame is
* permitted per GraphicsDevice. Attempts to
* construct a second Frame will cause the constructor to throw
* java.lang.UnsupportedOperationException. See:
*
* - {@link #Frame()}
*
- {@link #Frame(GraphicsConfiguration)}
*
- {@link #Frame(String)}
*
- {@link #Frame(String, GraphicsConfiguration)}
*
-
Frame.readObject()
*
*
*
*
*
* @version 1.139, 01/23/03
* @author Sami Shaio
* @see WindowEvent
* @see Window#addWindowListener
* @since JDK1.0
*/
public class Frame extends Window
{
// /**
// * @deprecated replaced by Cursor.DEFAULT_CURSOR.
// */
// public static final int DEFAULT_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.CROSSHAIR_CURSOR.
// */
// public static final int CROSSHAIR_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.TEXT_CURSOR.
// */
// public static final int TEXT_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.WAIT_CURSOR.
// */
// public static final int WAIT_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.SW_RESIZE_CURSOR.
// */
// public static final int SW_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.SE_RESIZE_CURSOR.
// */
// public static final int SE_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.NW_RESIZE_CURSOR.
// */
// public static final int NW_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.NE_RESIZE_CURSOR.
// */
// public static final int NE_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.N_RESIZE_CURSOR.
// */
// public static final int N_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.S_RESIZE_CURSOR.
// */
// public static final int S_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.W_RESIZE_CURSOR.
// */
// public static final int W_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.E_RESIZE_CURSOR.
// */
// public static final int E_RESIZE_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.HAND_CURSOR.
// */
// public static final int HAND_CURSOR = 0;
// /**
// * @deprecated replaced by Cursor.MOVE_CURSOR.
// */
// public static final int MOVE_CURSOR = 0;
/**
* Frame is in the "normal" state. This symbolic constant names a
* frame state with all state bits cleared.
*
*
*
*/
public static final int NORMAL = 0;
/**
* This state bit indicates that frame is iconified.
*
*
*
*/
public static final int ICONIFIED = 1;
// /**
// * This state bit indicates that frame is maximized in the
// * horizontal direction.
// * @see #setExtendedState(int)
// * @see #getExtendedState
// * @since 1.4
// */
// public static final int MAXIMIZED_HORIZ = 0;
//
// /**
// * This state bit indicates that frame is maximized in the
// * vertical direction.
// * @see #setExtendedState(int)
// * @see #getExtendedState
// * @since 1.4
// */
// public static final int MAXIMIZED_VERT = 0;
//
// /**
// * This state bit mask indicates that frame is fully maximized
// * (that is both horizontally and vertically). It is just a
// * convenience alias for
// * MAXIMIZED_VERT | MAXIMIZED_HORIZ.
// *
// * Note that the correct test for frame being fully maximized is
// *
// * (state & Frame.MAXIMIZED_BOTH) == Frame.MAXIMIZED_BOTH
// *
// *
// * To test is frame is maximized in some direction use
// *
// * (state & Frame.MAXIMIZED_BOTH) != 0
// *
// *
// * @see #setExtendedState(int)
// * @see #getExtendedState
// * @since 1.4
// */
// public static final int MAXIMIZED_BOTH = 0;
/**
* Maximized bounds for this frame.
* @see #setMaximizedBounds(Rectangle)
* @see #getMaximizedBounds
* @serial
* @since 1.4
*/
// Rectangle maximizedBounds;
/**
* This is the title of the frame. It can be changed
* at any time. title can be null and if
* this is the case the title = "".
*
* @serial
* @see #getTitle
* @see #setTitle(String)
*/
String title;
// /**
// * The frames menubar. If menuBar = null
// * the frame will not have a menubar.
// *
// * @serial
// * @see #getMenuBar
// * @see #setMenuBar(MenuBar)
// */
// MenuBar menuBar;
/**
* This field indicates whether the frame is resizable.
* This property can be changed at any time.
* resizable will be true if the frame is
* resizable, otherwise it will be false.
*
* @serial
* @see #isResizable()
*/
boolean resizable;
/**
* This field indicates whether the frame is undecorated.
* This property can only be changed while the frame is not displayable.
* undecorated will be true if the frame is
* undecorated, otherwise it will be false.
*
* @serial
* @see #setUndecorated(boolean)
* @see #isUndecorated()
* @see Component#isDisplayable()
* @since 1.4
*/
boolean undecorated;
/**
* mbManagement is only used by the Motif implementation.
*
* @serial
*/
boolean mbManagement;
private int state;
// PBP/PP 6203778
// Vector ownedWindows;
/**
* Frame's Serialized Data Version.
*
* @serial
*/
private int frameSerializedDataVersion;
/*
* JDK 1.1 serialVersionUID
*/
private static final long serialVersionUID = 2673458971256075116L;
// PBP/PP
/**
* Constructs a new instance of Frame that is
* initially invisible. The title of the Frame
* is empty.
*
* Note: This operation is subject to
* restriction
* in Personal Basis Profile.
* @exception HeadlessException when GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless()
* @see Component#setSize
* @see Component#setVisible(boolean)
*/
public Frame() throws HeadlessException { super(null); }
// PBP/PP
/**
* Create a Frame with the specified
* GraphicsConfiguration of
* a screen device.
*
*
* Note: This operation is subject to
* restriction
* in Personal Basis Profile.
*
* @param gc the GraphicsConfiguration
* of the target screen device. If gc
* is null, the system default
* GraphicsConfiguration is assumed.
* @exception IllegalArgumentException if
* gc is not from a screen device.
* This exception is always thrown
* when GraphicsEnvironment.isHeadless() returns true
* @see java.awt.GraphicsEnvironment#isHeadless()
* @since 1.3
*/
public Frame(GraphicsConfiguration gc) { super(null);}
// PBP/PP
/**
* Constructs a new, initially invisible Frame object
* with the specified title.
*
*
* Note: This operation is subject to
* restriction
* in Personal Basis Profile.
*
* @param title the title to be displayed in the frame's border.
* A null value
* is treated as an empty string, "".
* @exception HeadlessException when GraphicsEnvironment.isHeadless()
* returns true
* @see java.awt.GraphicsEnvironment#isHeadless()
* @see java.awt.Component#setSize
* @see java.awt.Component#setVisible(boolean)
* @see java.awt.GraphicsConfiguration#getBounds
*/
public Frame(String title) throws HeadlessException {super(null); }
// PBP/PP
/**
* Constructs a new, initially invisible Frame object
* with the specified title and a
* GraphicsConfiguration.
*
* Note: This operation is subject to
* restriction
* in Personal Basis Profile.
*
* @param title the title to be displayed in the frame's border.
* A null value
* is treated as an empty string, "".
* @param gc the GraphicsConfiguration
* of the target screen device. If gc is
* null, the system default
* GraphicsConfiguration is assumed.
* @exception IllegalArgumentException if gc
* is not from a screen device.
* This exception is always thrown
* when GraphicsEnvironment.isHeadless() returns true
* @see java.awt.GraphicsEnvironment#isHeadless()
* @see java.awt.Component#setSize
* @see java.awt.Component#setVisible(boolean)
* @see java.awt.GraphicsConfiguration#getBounds
*/
public Frame(String title, GraphicsConfiguration gc) {super(null); }
// /**
// * We have to remove the (hard) reference to weakThis in the
// * Vector, otherwise the WeakReference instance will never get
// * garbage collected.
// */
// protected void finalize() throws Throwable { }
// /**
// * Makes this Frame displayable by connecting it to
// * a native screen resource. Making a frame displayable will
// * cause any of its children to be made displayable.
// * This method is called internally by the toolkit and should
// * not be called directly by programs.
// * @see Component#isDisplayable
// * @see #removeNotify
// */
// public void addNotify() { }
/**
* Gets the title of the frame. The title is displayed in the
* frame's border.
* @return the title of this frame, or an empty string ("")
* if this frame doesn't have a title.
* @see #setTitle(String)
*/
public String getTitle() { return null; }
/**
* Sets the title for this frame to the specified string.
*
* @param title the title to be displayed in the frame's border.
* A null value
* is treated as an empty string, "".
* @see #getTitle
*/
public void setTitle(String title) { }
/**
* Gets the image to be displayed in the minimized icon
* for this frame.
* @return the icon image for this frame, or null
* if this frame doesn't have an icon image.
* @see #setIconImage(Image)
*/
public Image getIconImage() { return null; }
/**
* Sets the image to be displayed in the minimized icon for this frame.
* Not all platforms support the concept of minimizing a window.
* @param image the icon image to be displayed.
* If this parameter is null then the
* icon image is set to the default image, which may vary
* with platform.
* @see #getIconImage
*/
public synchronized void setIconImage(Image image) { }
// /**
// * Gets the menu bar for this frame.
// * @return the menu bar for this frame, or null
// * if this frame doesn't have a menu bar.
// * @see #setMenuBar(MenuBar)
// */
// public MenuBar getMenuBar() { return null; }
// /**
// * Sets the menu bar for this frame to the specified menu bar.
// * @param mb the menu bar being set.
// * If this parameter is null then any
// * existing menu bar on this frame is removed.
// * @see #getMenuBar
// */
// public void setMenuBar(MenuBar mb) { }
/**
* Indicates whether this frame is resizable by the user.
* By default, all frames are initially resizable.
* @return true if the user can resize this frame;
* false otherwise.
* @see java.awt.Frame#setResizable(boolean)
*/
public boolean isResizable() { return false; }
/**
* Sets whether this frame is resizable by the user.
*
* @param resizable true if this frame is resizable;
* false otherwise.
* @see java.awt.Frame#isResizable
*/
public void setResizable(boolean resizable) { }
// PBP/PP
// [6187196]
/**
* Sets the state of this frame.
*
*
*
*
*
*
*
* Note that if the state is not supported on a
* given platform, nothing will happen. The application
* may determine if a specific state is available via
* {@link Toolkit#isFrameStateSupported(int state)}.
*
*
* @param state either Frame.NORMAL or
* Frame.ICONIFIED.
* @see #getState
*/
public synchronized void setState(int state) { }
// /**
// * Sets the state of this frame. The state is
// * represented as a bitwise mask.
// *
// * NORMAL
// *
Indicates that no state bits are set.
// * ICONIFIED
// * MAXIMIZED_HORIZ
// * MAXIMIZED_VERT
// * MAXIMIZED_BOTH
// *
Concatenates MAXIMIZED_HORIZ
// * and MAXIMIZED_VERT.
// *
// * Note that if the state is not supported on a
// * given platform, nothing will happen. The application
// * may determine if a specific state is available via
// * the java.awt.Toolkit#isFrameStateSupported(int state)
// * method.
// *
// * @param state a bitwise mask of frame state constants
// * @see #getExtendedState
// * @see java.awt.Toolkit#isFrameStateSupported(int)
// * @since 1.4
// */
// public synchronized void setExtendedState(int state) { }
// PBP/PP
// [6187196]
/**
* Gets the state of this frame.
*
*
*
* @return Frame.NORMAL or Frame.ICONIFIED.
* @see #setState(int)
*/
public synchronized int getState() {return 0; }
// /**
// * Gets the state of this frame. The state is
// * represented as a bitwise mask.
// *
// * NORMAL
// *
Indicates that no state bits are set.
// * ICONIFIED
// * MAXIMIZED_HORIZ
// * MAXIMIZED_VERT
// * MAXIMIZED_BOTH
// *
Concatenates MAXIMIZED_HORIZ
// * and MAXIMIZED_VERT.
// *
// *
// * @return a bitwise mask of frame state constants
// * @see #setExtendedState(int)
// * @since 1.4
// */
// public synchronized int getExtendedState() { }
// /**
// * Sets the maximized bounds for this frame.
// *
// * When a frame is in maximized state the system supplies some
// * defaults bounds. This method allows some or all of those
// * system supplied values to be overridden.
// *
// * If bounds is null, accept bounds
// * supplied by the system. If non-null you can
// * override some of the system supplied values while accepting
// * others by setting those fields you want to accept from system
// * to Integer.MAX_VALUE.
// *
// * On some systems only the size portion of the bounds is taken
// * into account.
// *
// * @param bounds bounds for the maximized state
// * @see #getMaximizedBounds()
// * @since 1.4
// */
// public synchronized void setMaximizedBounds(Rectangle bounds) { }
//
// /**
// * Gets maximized bounds for this frame.
// * Some fields may contain Integer.MAX_VALUE to indicate
// * that system supplied values for this field must be used.
// *
// * @return maximized bounds for this frame; may be null
// * @see #setMaximizedBounds(Rectangle)
// * @since 1.4
// */
// public Rectangle getMaximizedBounds() { }
// PBP/PP
// [6187219]
/**
* Disables or enables decorations for this frame.
* This method can only be called while the frame is not displayable.
* @param undecorated true if no frame decorations are
* to be enabled;
* false if frame decorations are to be enabled.
* @throws IllegalComponentStateException if the frame
* is displayable.
* @see #isUndecorated
* @see Component#isDisplayable
*
*
* @since 1.4
*/
public void setUndecorated(boolean undecorated) { }
//
// PBP/PP
// 5087511 deleted assertion saying frame decorated by default
/**
* Indicates whether this frame is undecorated.
*
* @return true if frame is undecorated;
* false otherwise.
* @see java.awt.Frame#setUndecorated(boolean)
* @since 1.4
*/
public boolean isUndecorated() { return false; }
// /**
// * Removes the specified menu bar from this frame.
// * @param m the menu component to remove.
// * If m is null, then
// * no action is taken
// */
// public void remove(MenuComponent m) { }
// /**
// * Makes this Frame undisplayable by removing its connection
// * to its native screen resource. Making a Frame undisplayable
// * will cause any of its children to be made undisplayable.
// * This method is called by the toolkit internally and should
// * not be called directly by programs.
// * @see Component#isDisplayable
// * @see #addNotify
// */
// public void removeNotify() { }
/**
* Returns a string representing the state of this Frame.
* This method is intended to be used only for debugging purposes, and the
* content and format of the returned string may vary between
* implementations. The returned string may be empty but may not be
* null.
*
* @return the parameter string of this frame
*/
protected String paramString() { return null; }
// /**
// * @deprecated As of JDK version 1.1,
// * replaced by Component.setCursor(Cursor).
// */
// public void setCursor(int cursorType) { }
// /**
// * @deprecated As of JDK version 1.1,
// * replaced by Component.getCursor().
// */
// public int getCursorType() { return 0; }
// /**
// * Returns an array containing all Frames created by the application.
// * If called from an applet, the array will only include the Frames
// * accessible by that applet.
// * @since 1.2
// */
// public static Frame[] getFrames() { }
//
// /**
// * Gets the AccessibleContext associated with this Frame.
// * For frames, the AccessibleContext takes the form of an
// * AccessibleAWTFrame.
// * A new AccessibleAWTFrame instance is created if necessary.
// *
// * @return an AccessibleAWTFrame that serves as the
// * AccessibleContext of this Frame
// */
// public AccessibleContext getAccessibleContext() { }
// PBP/PP
/**
* Reads the ObjectInputStream. Tries
* to read an icon Image, which is optional
* data available as of 1.4. If an Image
* is not available, but anything other than an EOF
* is detected, an OptionalDataException
* will be thrown..
* Unrecognized keys or values will be ignored.
*
* Note: This operation is subject to
* restriction
* in Personal Basis Profile.
*
* @param s the ObjectInputStream to read
* @exception OptionalDataException if an Image
* is not available, but anything other than an EOF
* is detected
* @exception HeadlessException if
* GraphicsEnvironment.isHeadless returns
* true
* @see java.awt.GraphicsEnvironment#isHeadless()
*
* @see java.awt.Image
* @see #writeObject(ObjectOutputStream)
*/
private void readObject(ObjectInputStream s)
throws ClassNotFoundException, IOException, HeadlessException
{ }
// PBP/PP
// 6203787
/**
* Writes default serializable fields to stream. Writes
* an optional serializable icon Image, which is
* available as of 1.4.
*
* @param s the ObjectOutputStream to write
* @serialData an optional Image
*
* @see java.awt.Image
* @see #readObject(ObjectInputStream)
*/
private void writeObject(ObjectOutputStream s) throws IOException { }
// /**
// * This class implements accessibility support for the
// * Frame class. It provides an implementation of the
// * Java Accessibility API appropriate to frame user-interface elements.
// */
// protected class AccessibleAWTFrame extends Window.AccessibleAWTWindow
// {
//
// protected AccessibleAWTFrame() { }
//
// /**
// * Get the role of this object.
// *
// * @return an instance of AccessibleRole describing the role of the
// * object
// * @see AccessibleRole
// */
// public AccessibleRole getAccessibleRole() { }
//
// /**
// * Get the state of this object.
// *
// * @return an instance of AccessibleStateSet containing the current
// * state set of the object
// * @see AccessibleState
// */
// public AccessibleStateSet getAccessibleStateSet() { }
// }
}