KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > ISizeProvider


1 /*******************************************************************************
2  * Copyright (c) 2004, 2005 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.ui;
12
13
14 /**
15  * Interface implemented by objects that are capable of computing
16  * a preferred size
17  *
18  * @since 3.1
19  */
20 public interface ISizeProvider {
21
22     /**
23      * Constant used to indicate infinite size. This is equal to Integer.MAX_VALUE, ensuring
24      * that it is greater than any other integer.
25      */
26     public static final int INFINITE = Integer.MAX_VALUE;
27     
28     /**
29      * Returns a bitwise combination of flags indicating how and when computePreferredSize should
30      * be used. When called with horizontal=true, this indicates the usage of computePreferredSize(true,...)
31      * for computing widths. When called with horizontal=false, this indicates the usage of computeSize(false,...)
32      * for computing heights. These flags are used for optimization. Each flag gives the part more control
33      * over its preferred size but slows down the layout algorithm. Parts should return the minimum set
34      * of flags necessary to specify their constraints.
35      * <p>
36      * If the return value of this function ever changes, the part must call <code>flushLayout</code> before
37      * the changes will take effect.
38      * </p>
39      *
40      * <ul>
41      * <li>SWT.MAX: The part has a maximum size that will be returned by computePreferredSize(horizontal,
42      * INFINITE, someWidth, INFINITE)</li>
43      * <li>SWT.MIN: The part has a minimum size that will be returned by computePreferredSize(horizontal,
44      * INFINITE, someWidth, 0)</li>
45      * <li>SWT.WRAP: Indicates that computePreferredSize makes use of the availablePerpendicular argument. If this
46      * flag is not specified, then the third argument to computePreferredSize will always be set to
47      * INFINITE. The perpendicular size is expensive to compute, and it is usually only used
48      * for wrapping parts.
49      * <li>SWT.FILL: The part may not return the preferred size verbatim when computePreferredSize is
50      * is given a value between the minimum and maximum sizes. This is commonly used if the part
51      * wants to use a set of predetermined sizes instead of using the workbench-provided size.
52      * For example, computePreferredSize(horizontal, availableSpace, someWidth,
53      * preferredSize) may return the nearest predetermined size. Note that this flag should
54      * be used sparingly. It can prevent layout caching and cause the workbench layout algorithm
55      * to degrade to exponential worst-case runtime. If this flag is omitted, then
56      * computePreferredSize may be used to compute the minimum and maximum sizes, but not for
57      * anything in between.</li>
58      * </ul>
59      *
60      * @param width a value of true or false determines whether the return value applies when computing
61      * widths or heights respectively. That is, getSizeFlags(true) will be used when calling
62      * computePreferredSize(true,...)
63      * @return any bitwise combination of SWT.MAX, SWT.MIN, SWT.WRAP, and SWT.FILL
64      */
65     public int getSizeFlags(boolean width);
66     
67     /**
68      * <p>
69      * Returns the best size for this part, given the available width and height and the workbench's
70      * preferred size for the part. Parts can overload this to enforce a minimum size, maximum size,
71      * or a quantized set of preferred sizes. If width == true, this method computes a width in pixels.
72      * If width == false, this method computes a height. availableParallel and availablePerpendicular
73      * contain the space available, and preferredParallel contains the preferred result.
74      * </p>
75      *
76      * <p>
77      * This method returns an answer that is less than or equal to availableParallel and as
78      * close to preferredParallel as possible. Return values larger than availableParallel will
79      * be truncated.
80      * </p>
81      *
82      * <p>
83      * Most presentations will define a minimum size at all times, and a maximum size that only applies
84      * when maximized.
85      * </p>
86      *
87      * <p>
88      * The getSizeFlags method controls how frequently this method will be called and what information
89      * will be available when it is. Any subclass that specializes this method should also specialize
90      * getSizeFlags. computePreferredSize(width, INFINITE, someSize, 0) returns
91      * the minimum size of the control (if any). computePreferredSize(width, INFINITE, someSize,
92      * INFINITE) returns the maximum size of the control.
93      * </p>
94      *
95      * <p>
96      * Examples:
97      * <ul>
98      * <li>To maintain a constant size of 100x300 pixels: {return width ? 100 : 300}, getSizeFlags(boolean) must
99      * return SWT.MIN | SWT.MAX</li>
100      * <li>To grow without constraints: {return preferredResult;}, getSizeFlags(boolean) must return 0.</li>
101      * <li>To enforce a width that is always a multiple of 100 pixels, to a minimum of 100 pixels:
102      * <code>
103      * {
104      * if (width && preferredResult != INFINITE) {
105      * int result = preferredResult - ((preferredResult + 50) % 100) + 50;
106      * result = Math.max(100, Math.min(result, availableParallel - (availableParallel % 100)));
107      *
108      * return result;
109      * }
110      * return preferredResult;
111      * }
112      * </code>
113      * In this case, getSizeFlags(boolean width) must return (width ? SWT.FILL | SWT.MIN: 0)
114      * </ul>
115      * <li>To maintain a minimum area of 100000 pixels:
116      * <code>
117      * {return availablePerpendicular < 100 ? 1000 : 100000 / availablePerpendicular;}
118      * </code>
119      * getSizeFlags(boolean width) must return SWT.WRAP | SWT.MIN;
120      * </li>
121      * </p>
122      *
123      * @param width indicates whether a width (=true) or a height (=false) is being computed
124      * @param availableParallel available space. This is a width (pixels) if width == true, and a height (pixels)
125      * if width == false. A return value larger than this will be ignored.
126      * @param availablePerpendicular available space perpendicular to the direction being measured
127      * or INFINITE if unbounded (pixels). This
128      * is a height if width == true, or a height if width == false. Implementations will generally ignore this
129      * argument unless they contain wrapping widgets. Note this argument will only contain meaningful information
130      * if the part returns the SWT.WRAP flag from getSizeFlags(width)
131      * @param preferredResult preferred size of the control (pixels, <= availableParallel). Set to
132      * INFINITE if unknown or unbounded.
133      * @return returns the preferred size of the control (pixels). This is a width if width == true or a height
134      * if width == false. Callers are responsible for rounding down the return value if it is larger than
135      * availableParallel. If availableParallel is INFINITE, then a return value of INFINITE
136      * is permitted, indicating that the preferred size of the control is unbounded.
137      *
138      * @see ISizeProvider#getSizeFlags(boolean)
139      */
140     public int computePreferredSize(boolean width, int availableParallel, int availablePerpendicular, int preferredResult);
141 }
142
Popular Tags