Home » openjdk-7 » javax » swing » [javadoc | source]

    1   /*
    2    * Copyright (c) 2005, 2006, 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   package javax.swing;
   26   
   27   import java.awt.Graphics2D;
   28   
   29   /**
   30    * <p>A painting delegate. The Painter interface defines exactly one method,
   31    * <code>paint</code>. It is used in situations where the developer can change
   32    * the painting routine of a component without having to resort to subclassing
   33    * the component. It is also generically useful when doing any form of painting
   34    * delegation.</p>
   35    *
   36    * <p><code>Painter</code>s are simply encapsulations of Java2D code and make
   37    * it fairly trivial to reuse existing <code>Painter</code>s or to combine
   38    * them together. Implementations of this interface are also trivial to write,
   39    * such that if you can't find a <code>Painter</code> that does what you need,
   40    * you can write one with minimal effort. Writing a <code>Painter</code> requires
   41    * knowledge of Java2D.</p>
   42    *
   43    * <p>A <code>Painter</code> may be created with a type parameter. This type will be
   44    * expected in the <code>paint</code> method. For example, you may wish to write a
   45    * <code>Painter</code> that only works with subclasses of {@link java.awt.Component}.
   46    * In that case, when the <code>Painter</code> is declared, you may declare that
   47    * it requires a <code>Component</code>, allowing the paint method to be type safe. Ex:
   48    * <pre>
   49    * {@code
   50    * Painter<Component> p = new Painter<Component>() {
   51    *     public void paint(Graphics2D g, Component c, int width, int height) {
   52    *         g.setColor(c.getBackground());
   53    *         //and so forth
   54    *     }
   55    * }
   56    * }
   57    * </pre></p>
   58    *
   59    * <p>This interface makes no guarantees of threadsafety.</p>
   60    *
   61    * @author rbair
   62    */
   63   public interface Painter<T> {
   64       /**
   65        * <p>Renders to the given {@link java.awt.Graphics2D} object. Implementations
   66        * of this method <em>may</em> modify state on the <code>Graphics2D</code>, and are not
   67        * required to restore that state upon completion. In most cases, it is recommended
   68        * that the caller pass in a scratch graphics object. The <code>Graphics2D</code>
   69        * must never be null.</p>
   70        *
   71        * <p>State on the graphics object may be honored by the <code>paint</code> method,
   72        * but may not be. For instance, setting the antialiasing rendering hint on the
   73        * graphics may or may not be respected by the <code>Painter</code> implementation.</p>
   74        *
   75        * <p>The supplied object parameter acts as an optional configuration argument.
   76        * For example, it could be of type <code>Component</code>. A <code>Painter</code>
   77        * that expected it could then read state from that <code>Component</code> and
   78        * use the state for painting. For example, an implementation may read the
   79        * backgroundColor and use that.</p>
   80        *
   81        * <p>Generally, to enhance reusability, most standard <code>Painter</code>s ignore
   82        * this parameter. They can thus be reused in any context. The <code>object</code>
   83        * may be null. Implementations must not throw a NullPointerException if the object
   84        * parameter is null.</p>
   85        *
   86        * <p>Finally, the <code>width</code> and <code>height</code> arguments specify the
   87        * width and height that the <code>Painter</code> should paint into. More
   88        * specifically, the specified width and height instruct the painter that it should
   89        * paint fully within this width and height. Any specified clip on the
   90        * <code>g</code> param will further constrain the region.</p>
   91        *
   92        * <p>For example, suppose I have a <code>Painter</code> implementation that draws
   93        * a gradient. The gradient goes from white to black. It "stretches" to fill the
   94        * painted region. Thus, if I use this <code>Painter</code> to paint a 500 x 500
   95        * region, the far left would be black, the far right would be white, and a smooth
   96        * gradient would be painted between. I could then, without modification, reuse the
   97        * <code>Painter</code> to paint a region that is 20x20 in size. This region would
   98        * also be black on the left, white on the right, and a smooth gradient painted
   99        * between.</p>
  100        *
  101        * @param g The Graphics2D to render to. This must not be null.
  102        * @param object an optional configuration parameter. This may be null.
  103        * @param width width of the area to paint.
  104        * @param height height of the area to paint.
  105        */
  106       public void paint(Graphics2D g, T object, int width, int height);
  107   }

Home » openjdk-7 » javax » swing » [javadoc | source]