001: /*******************************************************************************
002: * Copyright (c) 2004, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui;
011:
012: /**
013: * Interface implemented by objects that are capable of computing
014: * a preferred size
015: *
016: * @since 3.1
017: */
018: public interface ISizeProvider {
019:
020: /**
021: * Constant used to indicate infinite size. This is equal to Integer.MAX_VALUE, ensuring
022: * that it is greater than any other integer.
023: */
024: public static final int INFINITE = Integer.MAX_VALUE;
025:
026: /**
027: * Returns a bitwise combination of flags indicating how and when computePreferredSize should
028: * be used. When called with horizontal=true, this indicates the usage of computePreferredSize(true,...)
029: * for computing widths. When called with horizontal=false, this indicates the usage of computeSize(false,...)
030: * for computing heights. These flags are used for optimization. Each flag gives the part more control
031: * over its preferred size but slows down the layout algorithm. Parts should return the minimum set
032: * of flags necessary to specify their constraints.
033: * <p>
034: * If the return value of this function ever changes, the part must call <code>flushLayout</code> before
035: * the changes will take effect.
036: * </p>
037: *
038: * <ul>
039: * <li>SWT.MAX: The part has a maximum size that will be returned by computePreferredSize(horizontal,
040: * INFINITE, someWidth, INFINITE)</li>
041: * <li>SWT.MIN: The part has a minimum size that will be returned by computePreferredSize(horizontal,
042: * INFINITE, someWidth, 0)</li>
043: * <li>SWT.WRAP: Indicates that computePreferredSize makes use of the availablePerpendicular argument. If this
044: * flag is not specified, then the third argument to computePreferredSize will always be set to
045: * INFINITE. The perpendicular size is expensive to compute, and it is usually only used
046: * for wrapping parts.
047: * <li>SWT.FILL: The part may not return the preferred size verbatim when computePreferredSize is
048: * is given a value between the minimum and maximum sizes. This is commonly used if the part
049: * wants to use a set of predetermined sizes instead of using the workbench-provided size.
050: * For example, computePreferredSize(horizontal, availableSpace, someWidth,
051: * preferredSize) may return the nearest predetermined size. Note that this flag should
052: * be used sparingly. It can prevent layout caching and cause the workbench layout algorithm
053: * to degrade to exponential worst-case runtime. If this flag is omitted, then
054: * computePreferredSize may be used to compute the minimum and maximum sizes, but not for
055: * anything in between.</li>
056: * </ul>
057: *
058: * @param width a value of true or false determines whether the return value applies when computing
059: * widths or heights respectively. That is, getSizeFlags(true) will be used when calling
060: * computePreferredSize(true,...)
061: * @return any bitwise combination of SWT.MAX, SWT.MIN, SWT.WRAP, and SWT.FILL
062: */
063: public int getSizeFlags(boolean width);
064:
065: /**
066: * <p>
067: * Returns the best size for this part, given the available width and height and the workbench's
068: * preferred size for the part. Parts can overload this to enforce a minimum size, maximum size,
069: * or a quantized set of preferred sizes. If width == true, this method computes a width in pixels.
070: * If width == false, this method computes a height. availableParallel and availablePerpendicular
071: * contain the space available, and preferredParallel contains the preferred result.
072: * </p>
073: *
074: * <p>
075: * This method returns an answer that is less than or equal to availableParallel and as
076: * close to preferredParallel as possible. Return values larger than availableParallel will
077: * be truncated.
078: * </p>
079: *
080: * <p>
081: * Most presentations will define a minimum size at all times, and a maximum size that only applies
082: * when maximized.
083: * </p>
084: *
085: * <p>
086: * The getSizeFlags method controls how frequently this method will be called and what information
087: * will be available when it is. Any subclass that specializes this method should also specialize
088: * getSizeFlags. computePreferredSize(width, INFINITE, someSize, 0) returns
089: * the minimum size of the control (if any). computePreferredSize(width, INFINITE, someSize,
090: * INFINITE) returns the maximum size of the control.
091: * </p>
092: *
093: * <p>
094: * Examples:
095: * <ul>
096: * <li>To maintain a constant size of 100x300 pixels: {return width ? 100 : 300}, getSizeFlags(boolean) must
097: * return SWT.MIN | SWT.MAX</li>
098: * <li>To grow without constraints: {return preferredResult;}, getSizeFlags(boolean) must return 0.</li>
099: * <li>To enforce a width that is always a multiple of 100 pixels, to a minimum of 100 pixels:
100: * <code>
101: * {
102: * if (width && preferredResult != INFINITE) {
103: * int result = preferredResult - ((preferredResult + 50) % 100) + 50;
104: * result = Math.max(100, Math.min(result, availableParallel - (availableParallel % 100)));
105: *
106: * return result;
107: * }
108: * return preferredResult;
109: * }
110: * </code>
111: * In this case, getSizeFlags(boolean width) must return (width ? SWT.FILL | SWT.MIN: 0)
112: * </ul>
113: * <li>To maintain a minimum area of 100000 pixels:
114: * <code>
115: * {return availablePerpendicular < 100 ? 1000 : 100000 / availablePerpendicular;}
116: * </code>
117: * getSizeFlags(boolean width) must return SWT.WRAP | SWT.MIN;
118: * </li>
119: * </p>
120: *
121: * @param width indicates whether a width (=true) or a height (=false) is being computed
122: * @param availableParallel available space. This is a width (pixels) if width == true, and a height (pixels)
123: * if width == false. A return value larger than this will be ignored.
124: * @param availablePerpendicular available space perpendicular to the direction being measured
125: * or INFINITE if unbounded (pixels). This
126: * is a height if width == true, or a height if width == false. Implementations will generally ignore this
127: * argument unless they contain wrapping widgets. Note this argument will only contain meaningful information
128: * if the part returns the SWT.WRAP flag from getSizeFlags(width)
129: * @param preferredResult preferred size of the control (pixels, <= availableParallel). Set to
130: * INFINITE if unknown or unbounded.
131: * @return returns the preferred size of the control (pixels). This is a width if width == true or a height
132: * if width == false. Callers are responsible for rounding down the return value if it is larger than
133: * availableParallel. If availableParallel is INFINITE, then a return value of INFINITE
134: * is permitted, indicating that the preferred size of the control is unbounded.
135: *
136: * @see ISizeProvider#getSizeFlags(boolean)
137: */
138: public int computePreferredSize(boolean width,
139: int availableParallel, int availablePerpendicular,
140: int preferredResult);
141: }
|