src/net/miginfocom/layout/ComponentWrapper.java

   1 package net.miginfocom.layout;
   2 /*
   3  * License (BSD):
   4  * ==============
   5  *
   6  * Copyright (c) 2004, Mikael Grev, MiG InfoCom AB. (miglayout (at) miginfocom (dot) com)
   7  * All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without modification,
  10  * are permitted provided that the following conditions are met:
  11  * Redistributions of source code must retain the above copyright notice, this list
  12  * of conditions and the following disclaimer.
  13  * Redistributions in binary form must reproduce the above copyright notice, this
  14  * list of conditions and the following disclaimer in the documentation and/or other
  15  * materials provided with the distribution.
  16  * Neither the name of the MiG InfoCom AB nor the names of its contributors may be
  17  * used to endorse or promote products derived from this software without specific
  18  * prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  22  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23  * IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
  24  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  26  * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  27  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
  29  * OF SUCH DAMAGE.
  30  *
  31  * @version 1.0
  32  * @author Mikael Grev, MiG InfoCom AB
  33  *         Date: 2006-sep-08
  34  */
  35
  36 /** A class that wraps the important parts of a Component.
  37  * <p>
  38  * <b>NOTE!</b>.equals() and .hashcode() should be forwarded to the wrapped component. E.g.
  39  * <pre>
  40  *      public int hashCode()
  41         {
  42                 return getComponent().hashCode();
  43         }
  44
  45         public final boolean equals(Object o)
  46         {
  47                  if (o instanceof ComponentWrapper == false)
  48                          return false;
  49
  50                  return getComponent().equals(((ComponentWrapper) o).getComponent());
  51         }
  52  * </pre>
  53  */
  54 public interface ComponentWrapper
  55 {
  56         static final int TYPE_UNSET = -1;
  57         public static final int TYPE_UNKNOWN = 0;
  58         public static final int TYPE_CONTAINER = 1;
  59         public static final int TYPE_LABEL = 2;
  60         public static final int TYPE_TEXT_FIELD = 3;
  61         public static final int TYPE_TEXT_AREA = 4;
  62         public static final int TYPE_BUTTON = 5;
  63         public static final int TYPE_LIST = 6;
  64         public static final int TYPE_TABLE = 7;
  65         public static final int TYPE_SCROLL_PANE = 8;
  66         public static final int TYPE_IMAGE = 9;
  67         public static final int TYPE_PANEL = 10;
  68         public static final int TYPE_COMBO_BOX = 11;
  69         public static final int TYPE_SLIDER = 12;
  70         public static final int TYPE_SPINNER = 13;
  71         public static final int TYPE_PROGRESS_BAR = 14;
  72         public static final int TYPE_TREE = 15;
  73         public static final int TYPE_CHECK_BOX = 16;
  74         public static final int TYPE_SCROLL_BAR = 17;
  75         public static final int TYPE_SEPARATOR = 18;
  76         public static final int TYPE_TABBED_PANE = 19;
  77
  78         /** Returns the actual object that this wrapper is aggregating. This might be needed for getting
  79          * information about the object that the wrapper interface does not provide.
  80          * <p>
  81          * If this is a container the container should be returned instead.
  82          * @return The actual object that this wrapper is aggregating. Not <code>null</code>.
  83          */
  84         public abstract Object getComponent();
  85
  86         /** Returns the current x coordinate for this component.
  87          * @return The current x coordinate for this component.
  88          */
  89         public abstract int getX();
  90
  91         /** Returns the current y coordinate for this component.
  92          * @return The current y coordinate for this component.
  93          */
  94         public abstract int getY();
  95
  96         /** Returns the current width for this component.
  97          * @return The current width for this component.
  98          */
  99         public abstract int getWidth();
 100
 101         /** Returns the current height for this component.
 102          * @return The current height for this component.
 103          */
 104         public abstract int getHeight();
 105
 106         /** Returns the screen x-coordinate for the upper left coordinate of the component layout-able bounds.
 107          * @return The screen x-coordinate for the upper left coordinate of the component layout-able bounds.
 108          */
 109         public abstract int getScreenLocationX();
 110
 111         /** Returns the screen y-coordinate for the upper left coordinate of the component layout-able bounds.
 112          * @return The screen y-coordinate for the upper left coordinate of the component layout-able bounds.
 113          */
 114         public abstract int getScreenLocationY();
 115
 116         /** Returns the minimum width of the component.
 117          * @param hHint The Size hint for the other dimension. An implementation can use this value or the
 118          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 119          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 120          * @return The minimum width of the component.
 121          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 122          * any implementing classes. This change was worth it though.
 123          */
 124         public abstract int getMinimumWidth(int hHint);
 125
 126         /** Returns the minimum height of the component.
 127          * @param wHint The Size hint for the other dimension. An implementation can use this value or the
 128          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 129          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 130          * @return The minimum height of the component.
 131          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 132          * any implementing classes. This change was worth it though.
 133          */
 134         public abstract int getMinimumHeight(int wHint);
 135
 136         /** Returns the preferred width of the component.
 137          * @param hHint The Size hint for the other dimension. An implementation can use this value or the
 138          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 139          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 140          * @return The preferred width of the component.
 141          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 142          * any implementing classes. This change was worth it though.
 143          */
 144         public abstract int getPreferredWidth(int hHint);
 145
 146         /** Returns the preferred height of the component.
 147          * @param wHint The Size hint for the other dimension. An implementation can use this value or the
 148          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 149          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 150          * @return The preferred height of the component.
 151          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 152          * any implementing classes. This change was worth it though.
 153          */
 154         public abstract int getPreferredHeight(int wHint);
 155
 156         /** Returns the maximum width of the component.
 157          * @param hHint The Size hint for the other dimension. An implementation can use this value or the
 158          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 159          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 160          * @return The maximum width of the component.
 161          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 162          * any implementing classes. This change was worth it though.
 163          */
 164         public abstract int getMaximumWidth(int hHint);
 165
 166         /** Returns the maximum height of the component.
 167          * @param wHint The Size hint for the other dimension. An implementation can use this value or the
 168          * current size for the widget in this dimension, or a combination of both, to calculate the correct size.<br>
 169          * Use -1 to denote that there is no hint. This corresponds with SWT.DEFAULT.
 170          * @return The maximum height of the component.
 171          * @since 3.5. Added the hint as a parameter knowing that a correction and recompilation is necessary for
 172          * any implementing classes. This change was worth it though.
 173          */
 174         public abstract int getMaximumHeight(int wHint);
 175
 176         /** Sets the component's bounds.
 177          * @param x The x coordinate.
 178          * @param y The y coordinate.
 179          * @param width The width.
 180          * @param height The height.
 181          */
 182         public abstract void setBounds(int x, int y, int width, int height);
 183
 184         /** Returns if the component's visibility is set to <code>true</code>. This should not return if the component is
 185          * actually visible, but if the visibility is set to true or not.
 186          * @return <code>true</code> means visible.
 187          */
 188         public abstract boolean isVisible();
 189
 190         /** Returns the baseline for the component given the suggested height.
 191          * @param width The width to calculate for if other than the current. If <code>-1</code> the current size should be used.
 192          * @param height The height to calculate for if other than the current. If <code>-1</code> the current size should be used.
 193          * @return The baseline from the top or -1 if not applicable.
 194          */
 195         public abstract int getBaseline(int width, int height);
 196
 197         /** Returns if the component has a baseline and if it can be retrieved. Should for instance return
 198          * <code>false</code> for Swing before mustang.
 199          * @return If the component has a baseline and if it can be retrieved.
 200          */
 201         public abstract boolean hasBaseline();
 202
 203         /** Returns the container for this component.
 204          * @return The container for this component. Will return <code>null</code> if the component has no parent.
 205          */
 206         public abstract ContainerWrapper getParent();
 207
 208         /** Returns the pixel unit factor for the horizontal or vertical dimension.
 209          * <p>
 210          * The factor is 1 for both dimensions on the normal font in a JPanel on Windows. The factor should increase with a bigger "X".
 211          * <p>
 212          * This is the Swing version:
 213          * <pre>
 214          * Rectangle2D r = fm.getStringBounds("X", parent.getGraphics());
 215          * wFactor = r.getWidth() / 6;
 216          * hFactor = r.getHeight() / 13.27734375f;
 217          * </pre>
 218          * @param isHor If it is the horizontal factor that should be returned.
 219          * @return The factor.
 220          */
 221         public abstract float getPixelUnitFactor(boolean isHor);
 222
 223         /** Returns the DPI (Dots Per Inch) of the screen the component is currently in or for the default
 224          * screen if the component is not visible.
 225          * <p>
 226          * If headless mode {@link net.miginfocom.layout.PlatformDefaults#getDefaultDPI} will be returned.
 227          * @return The DPI.
 228          */
 229         public abstract int getHorizontalScreenDPI();
 230
 231         /** Returns the DPI (Dots Per Inch) of the screen the component is currently in or for the default
 232          * screen if the component is not visible.
 233          * <p>
 234          * If headless mode {@link net.miginfocom.layout.PlatformDefaults#getDefaultDPI} will be returned.
 235          * @return The DPI.
 236          */
 237         public abstract int getVerticalScreenDPI();
 238
 239         /** Returns the pixel size of the screen that the component is currently in or for the default
 240          * screen if the component is not visible or <code>null</code>.
 241          * <p>
 242          * If in headless mode <code>1024</code> is returned.
 243          * @return The screen size. E.g. <code>1280</code>.
 244          */
 245         public abstract int getScreenWidth();
 246
 247         /** Returns the pixel size of the screen that the component is currently in or for the default
 248          * screen if the component is not visible or <code>null</code>.
 249          * <p>
 250          * If in headless mode <code>768</code> is returned.
 251          * @return The screen size. E.g. <code>1024</code>.
 252          */
 253         public abstract int getScreenHeight();
 254
 255         /** Returns a String id that can be used to reference the component in link constraints. This value should
 256          * return the default id for the component. The id can be set for a component in the constraints and if
 257          * so the value returned by this method will never be used. If there are no sensible id for the component
 258          * <code>null</code> should be returned.
 259          * <p>
 260          * For instance the Swing implementation returns the string returned from <code>Component.getName()</code>.
 261          * @return The string link id or <code>null</code>.
 262          */
 263         public abstract String getLinkId();
 264
 265         /** Returns a hash code that should be reasonably different for anything that might change the layout. This value is used to
 266          *  know if the component layout needs to clear any caches.
 267          * @return A hash code that should be reasonably different for anything that might change the layout. Returns -1 if the widget is
 268          * disposed.
 269          */
 270         public abstract int getLayoutHashCode();
 271
 272         /** Returns the padding on a component by component basis. This method can be overridden to return padding to compensate for example for
 273          * borders that have shadows or where the outer most pixel is not the visual "edge" to align to.
 274          * <p>
 275          * Default implementation returns <code>null</code> for all components except for Windows XP's JTabbedPane which will return new Insets(0, 0, 2, 2).
 276          * <p>
 277          * <b>NOTE!</B> To reduce generated garbage the returned padding should never be changed so that the same insets can be returned many times.
 278          * @return <code>null</code> if no padding. <b>NOTE!</B> To reduce generated garbage the returned padding should never be changed so that
 279          * the same insets can be returned many times. [top, left, bottom, right]
 280          */
 281         public int[] getVisualPadding();
 282
 283         /** Paints component outline to indicate where it is.
 284          * @param showVisualPadding If the visual padding should be shown in the debug drawing.
 285          */
 286         public abstract void paintDebugOutline(boolean showVisualPadding);
 287
 288         /** Returns the type of component that this wrapper is wrapping.
 289          * <p>
 290          * This method can be invoked often so the result should be cached.
 291          * <p>
 292          * @param disregardScrollPane Is <code>true</code> any wrapping scroll pane should be disregarded and the type
 293          * of the scrolled component should be returned.
 294          * @return The type of component that this wrapper is wrapping. E.g. {@link #TYPE_LABEL}.
 295          */
 296         public abstract int getComponentType(boolean disregardScrollPane);
 297
 298         /** Returns in what way the min/pref/max sizes relates to it's height or width for the current settings of the component (like wrapText).
 299          * If the min/pref/max height depends on it's width return {@link net.miginfocom.layout.LayoutUtil#HORIZONTAL}
 300          * If the min/pref/max width depends on it's height (not common) return {@link net.miginfocom.layout.LayoutUtil#VERTICAL}
 301          * If there is no connection between the preferred min/pref/max and the size of the component return -1.
 302          * @since 5.0
 303          */
 304         public abstract int getContentBias();
 305 }