001: /*
002: * @(#)DrawingSurfaceInfo.java 1.10 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.awt;
029:
030: import java.awt.Rectangle;
031: import java.awt.Shape;
032:
033: /**
034: * The DrawingSurfaceInfo object provides a common interface to
035: * access all information about how to gain access to the drawing
036: * surface controlled by some Java object. The information can
037: * be divided into two different categories, the logical drawing
038: * boundaries and the physical surface handle. The physical handle
039: * is represented by an implementation-specific object which the
040: * caller must be able to recognize in order to render directly to
041: * the surface. Many of the physical handles will be usable only
042: * by native code which accesses platform-specific drawing interfaces.
043: *
044: * @version 1.6, 08/19/02
045: * @author Jim Graham
046: */
047: public interface DrawingSurfaceInfo {
048: /**
049: * Lock the current state of the drawing surface in preparation
050: * for drawing to it and return an integer "change identifier"
051: * which can be used to determine when changes have occured to
052: * the drawing surface specification and when to retrieve new
053: * extent and physical handle data. If the identifier has not
054: * changed since the previous time lock and unlock were called
055: * then the consumer of this information is free to reuse clipping
056: * and handle information cached during the previous rendering
057: * operation. If the identifier changes, then all extent,
058: * clipping, and handle information must be retrieved again.
059: * The unlock() method must be called when rendering is complete
060: * or the component may be permanently locked down on the screen
061: * and other rendering threads may block indefinately.
062: */
063: public int lock();
064:
065: /**
066: * Unlock the drawing surface and allow other threads to
067: * access or change its composition.
068: */
069: public void unlock();
070:
071: /**
072: * Returns a rectangle describing the logical bounds of the given
073: * screen object relative to the "drawing handle" information
074: * returned by getSurface(). Note that there may be portions
075: * of this bounding rectangle that are obscured. This value
076: * defines the location of the logical upper-left origin of
077: * the component or screen object and its desired extents
078: * (which may differ from the clipping extents due to the
079: * presence of other overlapping screen objects). The getClip()
080: * method should be used to determine which portions of the
081: * drawing surface can actually be drawn to.
082: */
083: public Rectangle getBounds();
084:
085: /**
086: * Returns an implementation-specific object which describes a
087: * handle to the physical drawing surface on which this screen
088: * object resides. Depending on the type of the return value,
089: * this object may describe a Windows hWnd handle, an X11
090: * drawable handle, a Mac GrafPtr structure, or some other
091: * platform-specific handle.
092: */
093: public PhysicalDrawingSurface getSurface();
094:
095: /**
096: * Returns an explicit representation of the renderable portion
097: * of the given screen object. This clipping area will include
098: * only those areas of the screen object that are not obscured
099: * by other overlapping objects and which fall within the
100: * boundaries of the physical drawing surface. The area described
101: * by the return value of this method can be directly used as a
102: * graphics clip area to restrict rendering to the given screen
103: * object.
104: */
105: public Shape getClip();
106: }
|