001: /*
002: * @(#)Window.java 1.23 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package sun.porting.windowsystem;
029:
030: import java.awt.*;
031:
032: /**
033: * This is the public interface for a window object. In this context it
034: * is a relatively low-level object (not to be confused with java.awt.Window)
035: * which underlies the implementation of a set of toolkit peers.
036: * <code>Window</code> has only a small number of capabilities:
037: * <ul>
038: * <li> It is an opaque, clipped drawing surface (i.e. has a background color)
039: * <li> Its size can be dynamically changed
040: * <li> It is capable of being the target for input events
041: * <li> It can contain other Windows in a strict hierarchical fashion
042: * <li> It can exist without being visible (i.e. "mapped")
043: * </ul>
044: * Finally, <code>Window</code> encapsulates some additional state:
045: * <ul>
046: * <li> X, Y position relative to its parent
047: * <li> Z order with respect to its siblings
048: * <li> keyboard and input focus
049: * <li> an associated cursor image
050: * </ul>
051: *
052: * @version 1.18, 08/19/02
053: */
054: public interface Window {
055: /**
056: * Get a graphics object for this window. The <code>Graphics</code> object
057: * which is returned will be created with a <code>GeometryProvider</code> which
058: * corresponds to this window; as a result, all drawing operations
059: * using this <code>Graphics</code> object will be located within, and clipped
060: * to this window.
061: */
062: public Graphics getGraphics();
063:
064: /**
065: * Get the location and size of the window. If global is true,
066: * the position will be returned in root coordinates; otherwise
067: * they will be relative to this window's parent.
068: * @param global A flag indicating whether to return x and y in
069: * global or parent-relative coordinates.
070: * @return The position and size in pixels, as a <code>Rectangle</code> object.
071: * @throws IllegalStateException if the window has been disposed.
072: */
073: Rectangle getBounds(boolean global) throws IllegalStateException;
074:
075: /**
076: * Set the location and/or size of the window. x and y are relative
077: * to this window's parent.
078: * @param x x coordinate of the upper left corner, relative to parent.
079: * @param y y coordinate of the upper left corner, relative to parent.
080: * @param w width in pixels.
081: * @param h height in pixels.
082: * @throws IllegalStateException if the window has been disposed.
083: */
084: void setBounds(int x, int y, int w, int h)
085: throws IllegalStateException;
086:
087: /**
088: * Move this window so that it is Nth in its list of siblings.
089: * N = 0 moves the window to the front; N = -1 moves it to the back.
090: * N = -2 moves it so it is above only the last window, etc.
091: * @throws IllegalStateException if the window has been disposed.
092: */
093: void setStackingOrder(int n) throws IllegalStateException;
094:
095: /**
096: * Set the background color for the window (i.e. the color which
097: * will be used to erase it when damage occurs, etc.)
098: */
099: void setBackgroundColor(Color c);
100:
101: /**
102: * Get the background color for the window (i.e. the color which
103: * will be used to erase it when damage occurs, etc.)
104: * @return The background color, as a <code>Color</code> object.
105: */
106: Color getBackgroundColor();
107:
108: /**
109: * Query the map state of the window
110: * @return true if the window is mapped (visible) false otherwise.
111: * @throws IllegalStateException if the window has been disposed.
112: */
113: boolean isMapped() throws IllegalStateException;
114:
115: /**
116: * Make this window visible.
117: * @throws IllegalStateException if the window has been disposed.
118: */
119: void map() throws IllegalStateException;
120:
121: /**
122: * Make this window invisible.
123: * If the window has the grab or the input focus, implicitly releases them.
124: * @throws IllegalStateException if the window has been disposed.
125: */
126: void unmap() throws IllegalStateException;
127:
128: /**
129: * Dispose of any resources associated with the window, and mark it invalid.
130: * If the window has the grab or the input focus, implicitly releases them.
131: */
132: void dispose();
133:
134: /**
135: * Determine whether this window has the keyboard input focus.
136: * @return true if this window has keyboard input focus, false otherwise.
137: * @throws IllegalStateException if the window has been disposed.
138: */
139: boolean hasInputFocus() throws IllegalStateException;
140:
141: /**
142: * Assign the keyboard input focus to this window.
143: * @throws IllegalStateException if the window is disposed or not mapped.
144: */
145: void acquireInputFocus() throws IllegalStateException;
146:
147: /**
148: * Determine whether this window (actually its top-level ancestor)
149: * owns the input grab.
150: * @return true if this window has the grab, false otherwise.
151: * @throws IllegalStateException if the window has been disposed.
152: */
153: boolean hasGrab() throws IllegalStateException;
154:
155: /**
156: * Delivery mode for grab: deliver all events to the grab window.
157: */
158: static final int DELIVER_ALL = 1;
159: /**
160: * Delivery mode for grab: discard events not directed to the grabbing
161: * window. Some auditory and/or visual feedback should accompany each
162: * discarded event.
163: */
164: static final int DISCARD_NOISY = 2;
165: /**
166: * Delivery mode for grab: discard events not directed to the grabbing
167: * window, giving no feedback.
168: */
169: static final int DISCARD_SILENT = 3;
170:
171: /**
172: * Make this window grab all input. <b>Does not change keyboard focus.</b>
173: * If this window is not a top-level window, the grab will be given to
174: * its top-level ancestor instead. The mode argument indicates what
175: * should be done with events that are not directed at the grab window.
176: * @param mode how to handle events directed at other windows.
177: * @throws IllegalStateException if the window is disposed or not mapped,
178: * or if the grab is owned by someone else.
179: * <strong>Important note: the actual window that owns the explicit grab
180: * must always be a top-level window. It is the window system's
181: * responsibility to find the top-level ancestor when grabbing, and to
182: * ensure that the event target is owned by (not necessarily equal to)
183: * the grab owner.</strong>
184: */
185: void grabInput(int mode) throws IllegalStateException;
186:
187: /**
188: * Make this window (or its top-level ancestor) release the grab.
189: * <b>Does not change keyboard focus.</b> Only explicitly-acquired
190: * grabs can be released by this method.
191: * @throws IllegalStateException if the window does not have the grab
192: * or has been disposed.
193: */
194: void releaseGrab() throws IllegalStateException;
195:
196: /**
197: * Set the cursor image to match the one supplied.
198: * @param image The contents of the cursor image
199: * @param hotX The x coordinate of the hotspot
200: * @param hotY The y coordinate of the hotspot
201: * @see sun.porting.graphicssystem.CursorImage
202: */
203: void setCursorImage(sun.porting.graphicssystem.CursorImage image);
204:
205: /**
206: * Set the window's "user data" field to the given object.
207: * This is a convenience for <code>Toolkit</code> implementors which allows
208: * them to efficiently associate private data with each window.
209: */
210: void setUserData(java.lang.Object o);
211:
212: /**
213: * Return the window's "user data" field.
214: * This is a convenience for <code>Toolkit</code> implementors which allows
215: * them to efficiently associate private data with each window.
216: */
217: java.lang.Object getUserData();
218: }
|