1 /*
   2  * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package sun.swing;
  27 
  28 import javax.swing.JComponent;
  29 
  30 /**
  31  * The interface by means of which the {@link JLightweightFrame} class
  32  * communicates to its client application.
  33  * <p>
  34  * The client application implements this interface so it can response
  35  * to requests and process notifications from {@code JLightweightFrame}.
  36  * An implementation of this interface is associated with a {@code
  37  * JLightweightFrame} instance via the {@link JLightweightFrame#setContent}
  38  * method.
  39  * 
  40  * A hierarchy of components contained in the {@code JComponent} instance
  41  * returned by the {@link #getComponent} method should not contain any
  42  * heavyweight components, otherwise {@code JLightweightFrame} may fail
  43  * to paint it.
  44  * 
  45  * @author Artem Ananiev
  46  * @author Anton Tarasov
  47  * @author Jim Graham
  48  */
  49 public interface LightweightContent {
  50 
  51     /**
  52      * The client application overrides this method to return the {@code
  53      * JComponent} instance which the {@code JLightweightFrame} container
  54      * will paint as its lightweight content. A hierarchy of components
  55      * contained in this component should not contain any heavyweight objects.
  56      * 
  57      * @return the component to paint
  58      */
  59     public JComponent getComponent();
  60 
  61     /**
  62      * {@code JLightweightFrame} calls this method to notify the client
  63      * application that it acquires the paint lock. The client application
  64      * should implement the locking mechanism in order to synchronize access
  65      * to the content image data, shared between {@code JLightweightFrame}
  66      * and the client application.
  67      * 
  68      * @see #paintUnlock
  69      */
  70     public void paintLock();
  71 
  72     /**
  73      * {@code JLightweightFrame} calls this method to notify the client
  74      * application that it releases the paint lock. The client application
  75      * should implement the locking mechanism in order to synchronize access
  76      * to the content image data, shared between {@code JLightweightFrame}
  77      * and the client application.
  78      * 
  79      * @see #paintLock
  80      */
  81     public void paintUnlock();
  82     
  83     /**
  84      * {@code JLightweightFrame} calls this method to notify the client
  85      * application that a new data buffer has been set as a content pixel
  86      * buffer. Typically this occurs when a buffer of a larger size is
  87      * created in response to a content resize event. The method reports
  88      * a reference to the pixel data buffer, the content image bounds
  89      * within the buffer and the line stride of the buffer. These values
  90      * have the following correlation.
  91      * <p>
  92      * The {@code width} and {@code height} matches the size of the content
  93      * (the component returned from the {@link #getComponent} method). The
  94      * {@code x} and {@code y} is the origin of the content, {@code (0, 0)}
  95      * in the coordinate space of the content, appearing at
  96      * {@code data[y * linestride + x]} in the buffer. All indices
  97      * {@code data[(y + j) * linestride + (x + i)]} where
  98      * {@code (0 <= i < width)} and {@code (0 <= j < height)} will represent
  99      * valid pixel data, {@code (i, j)} in the coordinate space of the content.
 100      * 
 101      * @param data the content pixel data buffer of INT_ARGB_PRE type
 102      * @param x the x coordinate of the image
 103      * @param y the y coordinate of the image
 104      * @param width the width of the image
 105      * @param height the height of the image
 106      * @param linestride the line stride of the pixel buffer
 107      */
 108     public void imageBufferReset(int[] data,
 109                                  int x, int y,
 110                                  int width, int height,
 111                                  int linestride);
 112     
 113     /**
 114      * {@code JLightweightFrame} calls this method to notify the client
 115      * application that the content image bounds have been changed within the
 116      * image's pixel buffer.
 117      * 
 118      * @param x the x coordinate of the image
 119      * @param y the y coordinate of the image
 120      * @param width the width of the image
 121      * @param height the height of the image
 122      * 
 123      * @see #imageBufferReset
 124      */
 125     public void imageReshaped(int x, int y, int width, int height);
 126     
 127     /**
 128      * {@code JLightweightFrame} calls this method to notify the client
 129      * application that a part of the content image, or the whole image has
 130      * been updated. The method reports bounds of the rectangular dirty region.
 131      * The {@code dirtyX} and {@code dirtyY} is the origin of the dirty
 132      * rectangle, which is relative to the origin of the content, appearing
 133      * at {@code data[(y + dirtyY] * linestride + (x + dirtyX)]} in the pixel
 134      * buffer (see {@link #imageBufferReset}). All indices
 135      * {@code data[(y + dirtyY + j) * linestride + (x + dirtyX + i)]} where
 136      * {@code (0 <= i < dirtyWidth)} and {@code (0 <= j < dirtyHeight)}
 137      * will represent valid pixel data, {@code (i, j)} in the coordinate space
 138      * of the dirty rectangle.
 139      * 
 140      * @param dirtyX the x coordinate of the dirty rectangle,
 141      *        relative to the image origin
 142      * @param dirtyY the y coordinate of the dirty rectangle,
 143      *        relative to the image origin
 144      * @param dirtyWidth the width of the dirty rectangle
 145      * @param dirtyHeight the height of the dirty rectangle
 146      * 
 147      * @see #imageBufferReset
 148      * @see #imageReshaped
 149      */
 150     public void imageUpdated(int dirtyX, int dirtyY,
 151                              int dirtyWidth, int dirtyHeight);
 152     
 153     /**
 154      * {@code JLightweightFrame} calls this method to notify the client
 155      * application that the frame has grabbed focus.
 156      */
 157     public void focusGrabbed();
 158     
 159     /**
 160      * {@code JLightweightFrame} calls this method to notify the client
 161      * application that the frame has ungrabbed focus.
 162      */
 163     public void focusUngrabbed();
 164 }