KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > layout > GridDataFactory


1 /*******************************************************************************
2  * Copyright (c) 2005, 2007 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  * Stefan Xenos, IBM - initial implementation, bug 178888
11  *******************************************************************************/
12 package org.eclipse.jface.layout;
13 import org.eclipse.swt.SWT;
14 import org.eclipse.swt.graphics.Point;
15 import org.eclipse.swt.layout.GridData;
16 import org.eclipse.swt.widgets.Control;
17
18 /**
19  * This class provides a convienient shorthand for creating and initializing
20  * GridData. This offers several benefits over creating GridData normal way:
21  *
22  * <ul>
23  * <li>The same factory can be used many times to create several GridData instances</li>
24  * <li>The setters on GridDataFactory all return "this", allowing them to be chained</li>
25  * <li>GridDataFactory uses vector setters (it accepts Points), making it easy to
26  * set X and Y values together</li>
27  * </ul>
28  *
29  * <p>
30  * GridDataFactory instances are created using one of the static methods on this class.
31  * </p>
32  *
33  * <p>
34  * Example usage:
35  * </p>
36  * <code><pre>
37  *
38  * ////////////////////////////////////////////////////////////
39  * // Example 1: Typical grid data for a non-wrapping label
40  *
41  * // GridDataFactory version
42  * GridDataFactory.fillDefaults().applyTo(myLabel);
43  *
44  * // Equivalent SWT version
45  * GridData labelData = new GridData(GridData.HORIZONTAL_ALIGN_FILL | GridData.VERTICAL_ALIGN_FILL);
46  * myLabel.setLayoutData(labelData);
47  *
48  * ///////////////////////////////////////////////////////////
49  * // Example 2: Typical grid data for a wrapping label
50  *
51  * // GridDataFactory version
52  * GridDataFactory.fillDefaults()
53  * .align(SWT.FILL, SWT.CENTER)
54  * .hint(150, SWT.DEFAULT)
55  * .grab(true, false)
56  * .applyTo(wrappingLabel);
57  *
58  * // Equivalent SWT version
59  * GridData wrappingLabelData = new GridData(GridData.FILL_HORIZONTAL | GridData.VERTICAL_ALIGN_CENTER);
60  * wrappingLabelData.minimumWidth = 1;
61  * wrappingLabelData.widthHint = 150;
62  * wrappingLabel.setLayoutData(wrappingLabelData);
63  *
64  * //////////////////////////////////////////////////////////////
65  * // Example 3: Typical grid data for a scrollable control (a list box, tree, table, etc.)
66  *
67  * // GridDataFactory version
68  * GridDataFactory.fillDefaults().grab(true, true).hint(150, 150).applyTo(listBox);
69  *
70  * // Equivalent SWT version
71  * GridData listBoxData = new GridData(GridData.FILL_BOTH);
72  * listBoxData.widthHint = 150;
73  * listBoxData.heightHint = 150;
74  * listBoxData.minimumWidth = 1;
75  * listBoxData.minimumHeight = 1;
76  * listBox.setLayoutData(listBoxData);
77  *
78  * /////////////////////////////////////////////////////////////
79  * // Example 4: Typical grid data for a button
80  *
81  * // GridDataFactory version
82  * Point preferredSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);
83  * Point hint = Geometry.max(LayoutConstants.getMinButtonSize(), preferredSize);
84  * GridDataFactory.fillDefaults().align(SWT.FILL, SWT.CENTER).hint(hint).applyTo(button);
85  *
86  * // Equivalent SWT version
87  * Point preferredSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, false);
88  * Point hint = Geometry.max(LayoutConstants.getMinButtonSize(), preferredSize);
89  * GridData buttonData = new GridData(GridData.HORIZONTAL_ALIGN_FILL | GridData.VERTICAL_ALIGN_CENTER);
90  * buttonData.widthHint = hint.x;
91  * buttonData.heightHint = hint.y;
92  * button.setLayoutData(buttonData);
93  *
94  * /////////////////////////////////////////////////////////////
95  * // Example 5: Generated GridData
96  *
97  * // Generates GridData a wrapping label that spans 2 columns
98  * GridDataFactory.generate(wrappingLabel, 2, 1);
99  *
100  * // Generates GridData for a listbox. and adjusts the preferred size to 300x400 pixels
101  * GridDataFactory.defaultsFor(listBox).hint(300, 400).applyTo(listBox);
102  *
103  * // Generates GridData equivalent to example 4
104  * GridDataFactory.generate(button, 1, 1);
105  *
106  * </pre></code>
107  *
108  * @since 3.2
109  */
110 public final class GridDataFactory {
111     private GridData data;
112     
113     /**
114      * Creates a GridDataFactory that creates copes of the given GridData.
115      *
116      * @param d template GridData to copy
117      */
118     private GridDataFactory(GridData d) {
119         this.data = d;
120     }
121     
122     /**
123      * Creates a new GridDataFactory initialized with the SWT defaults.
124      * This factory will generate GridData that is equivalent to
125      * "new GridData()".
126      *
127      * <p>
128      * Initial values are:
129      * </p>
130      *
131      * <ul>
132      * <li>align(SWT.BEGINNING, SWT.CENTER)</li>
133      * <li>exclude(false)</li>
134      * <li>grab(false, false)</li>
135      * <li>hint(SWT.DEFAULT, SWT.DEFAULT)</li>
136      * <li>indent(0,0)</li>
137      * <li>minSize(0,0)</li>
138      * <li>span(1,1)</li>
139      * </ul>
140      *
141      * @return a new GridDataFactory instance
142      * @see #fillDefaults()
143      */
144     public static GridDataFactory swtDefaults() {
145         return new GridDataFactory(new GridData());
146     }
147     
148     /**
149      * Creates a new GridDataFactory that creates copies of the given GridData
150      * by default.
151      *
152      * @param data GridData to copy
153      * @return a new GridDataFactory that creates copies of the argument by default
154      */
155     public static GridDataFactory createFrom(GridData data) {
156         return new GridDataFactory(copyData(data));
157     }
158     
159     /**
160      * Creates a GridDataFactory initialized with defaults that will cause
161      * the control to fill its cell. The minimum size is set to the smallest possible
162      * minimum size supported by SWT. Currently, the smallest supported minimum size
163      * is (1,1) so this is the default. If GridLayout ever adds support for grid data
164      * with no minimum size, this will be changed to 0,0 in the future.
165      *
166      * <p>
167      * Initial values are:
168      * </p>
169      *
170      * <ul>
171      * <li>align(SWT.FILL, SWT.FILL)</li>
172      * <li>exclude(false)</li>
173      * <li>grab(false, false)</li>
174      * <li>hint(SWT.DEFAULT, SWT.DEFAULT)</li>
175      * <li>indent(0,0)</li>
176      * <li>minSize(1,1)</li>
177      * <li>span(1,1)</li>
178      * </ul>
179      *
180      * @return a GridDataFactory that makes controls fill their grid by default
181      *
182      * @see #swtDefaults()
183      */
184     public static GridDataFactory fillDefaults() {
185         GridData data = new GridData();
186         data.minimumWidth = 1;
187         data.minimumHeight = 1;
188         data.horizontalAlignment = SWT.FILL;
189         data.verticalAlignment = SWT.FILL;
190         
191         return new GridDataFactory(data);
192     }
193     
194     /**
195      * Returns a GridDataFactory initialized with heuristicly generated defaults for the given control.
196      * To be precise, this method picks the default values that GridLayoutFactory.generateLayout
197      * would have assigned to the control. Does not attach GridData to the control. Callers must
198      * additionally call applyTo(theControl) if they wish to use the generated values.
199      *
200      * <p>
201      * This method is intended for situations where generateLayout is generating layout data
202      * for a particular control that is not quite right for the desired layout.
203      * This allows callers to start with the generated values and tweak one or two settings
204      * before applying the GridData to the control.
205      * </p>
206      *
207      * @see GridLayoutFactory#generateLayout(org.eclipse.swt.widgets.Composite)
208      * @param theControl
209      * @return a GridLayoutFactory initialized with defaults that GridLayoutFactory would have
210      * @since 3.3
211      */
212     public static GridDataFactory defaultsFor(Control theControl) {
213         return LayoutGenerator.defaultsFor(theControl);
214     }
215     
216     /**
217      * Generates layout data to the given control, given the number of cells
218      * spanned by the control. Attaches a GridData to the control. This method
219      * allows generated layout data to be used with controls that span multiple cells.
220      * <p>
221      * The generated layout data is the same as what would be generated by
222      * GridLayoutFactory.generateLayout, except that the span is configurable
223      * </p>
224      *
225      * @see GridLayoutFactory#generateLayout(org.eclipse.swt.widgets.Composite)
226      * @param theControl
227      * @param hSpan number of columns spanned by the control
228      * @param vSpan number of rows spanned by the control
229      * @since 3.3
230      */
231     public static void generate(Control theControl, int hSpan, int vSpan) {
232         defaultsFor(theControl).span(hSpan, vSpan).applyTo(theControl);
233     }
234
235     /**
236      * Generates layout data to the given control, given the number of cells
237      * spanned by the control. Attaches GridData to the control. This method
238      * allows generated layout data to be used with controls that span multiple cells.
239      * <p>
240      * The generated layout data is the same as what would be generated by
241      * GridLayoutFactory.generateLayout, except that the span is configurable
242      * </p>
243      *
244      * @see GridLayoutFactory#generateLayout(org.eclipse.swt.widgets.Composite)
245      * @param theControl
246      * @param span The x coordinate indicates the number of
247      * columns spanned, and the y coordinate indicates the number of rows.
248      * @since 3.3
249      */
250     public static void generate(Control theControl, Point span) {
251         defaultsFor(theControl).span(span).applyTo(theControl);
252     }
253     
254     /**
255      * Sets the GridData span. The span controls how many cells
256      * are filled by the control.
257      *
258      * @param hSpan number of columns spanned by the control
259      * @param vSpan number of rows spanned by the control
260      * @return this
261      */
262     public GridDataFactory span(int hSpan, int vSpan) {
263         data.horizontalSpan = hSpan;
264         data.verticalSpan = vSpan;
265         return this;
266     }
267
268     /**
269      * Sets the GridData span. The span controls how many cells
270      * are filled by the control.
271      *
272      * @param span the new span. The x coordinate indicates the number of
273      * columns spanned, and the y coordinate indicates the number of rows.
274      * @return this
275      */
276     public GridDataFactory span(Point span) {
277         data.horizontalSpan = span.x;
278         data.verticalSpan = span.y;
279         return this;
280     }
281
282     /**
283      * Sets the width and height hints. The width and height hints override
284      * the control's preferred size. If either hint is set to SWT.DEFAULT,
285      * the control's preferred size is used.
286      *
287      * @param xHint horizontal hint (pixels), or SWT.DEFAULT to use the control's preferred size
288      * @param yHint vertical hint (pixels), or SWT.DEFAULT to use the control's preferred size
289      * @return this
290      */
291     public GridDataFactory hint(int xHint, int yHint) {
292         data.widthHint = xHint;
293         data.heightHint = yHint;
294         return this;
295     }
296
297     /**
298      * Sets the width and height hints. The width and height hints override
299      * the control's preferred size. If either hint is set to SWT.DEFAULT,
300      * the control's preferred size is used.
301      *
302      * @param hint size (pixels) to be used instead of the control's preferred size. If
303      * the x or y values are set to SWT.DEFAULT, the control's computeSize() method will
304      * be used to obtain that dimension of the preferred size.
305      * @return this
306      */
307     public GridDataFactory hint(Point hint) {
308         data.widthHint = hint.x;
309         data.heightHint = hint.y;
310         return this;
311     }
312
313     /**
314      * Sets the alignment of the control within its cell.
315      *
316      * @param hAlign horizontal alignment. One of SWT.BEGINNING, SWT.CENTER, SWT.END, or SWT.FILL.
317      * @param vAlign vertical alignment. One of SWT.BEGINNING, SWT.CENTER, SWT.END, or SWT.FILL.
318      * @return this
319      */
320     public GridDataFactory align(int hAlign, int vAlign) {
321         if (hAlign != SWT.BEGINNING && hAlign != SWT.CENTER && hAlign != GridData.CENTER && hAlign != SWT.END && hAlign != GridData.END && hAlign != SWT.FILL && hAlign != SWT.LEFT && hAlign != SWT.RIGHT) {
322             throw new IllegalArgumentException JavaDoc();
323         }
324         if (vAlign != SWT.BEGINNING && vAlign != SWT.CENTER && vAlign != GridData.CENTER && vAlign != SWT.END && vAlign != GridData.END && vAlign != SWT.FILL && vAlign != SWT.TOP && vAlign != SWT.BOTTOM) {
325             throw new IllegalArgumentException JavaDoc();
326         }
327         data.horizontalAlignment = hAlign;
328         data.verticalAlignment = vAlign;
329         return this;
330     }
331
332     /**
333      * Sets the indent of the control within the cell. Moves the position of the control
334      * by the given number of pixels. Positive values move toward the lower-right, negative
335      * values move toward the upper-left.
336      *
337      * @param hIndent distance to move to the right (negative values move left)
338      * @param vIndent distance to move down (negative values move up)
339      * @return this
340      */
341     public GridDataFactory indent(int hIndent, int vIndent) {
342         data.horizontalIndent = hIndent;
343         data.verticalIndent = vIndent;
344         return this;
345     }
346
347     /**
348      * Sets the indent of the control within the cell. Moves the position of the control
349      * by the given number of pixels. Positive values move toward the lower-right, negative
350      * values move toward the upper-left.
351      *
352      * @param indent offset to move the control
353      * @return this
354      */
355     public GridDataFactory indent(Point indent) {
356         data.horizontalIndent = indent.x;
357         data.verticalIndent = indent.y;
358         return this;
359     }
360
361     /**
362      * Determines whether extra horizontal or vertical space should be allocated to
363      * this control's column when the layout resizes. If any control in the column
364      * is set to grab horizontal then the whole column will grab horizontal space.
365      * If any control in the row is set to grab vertical then the whole row will grab
366      * vertical space.
367      *
368      * @param horizontal true if the control's column should grow horizontally
369      * @param vertical true if the control's row should grow vertically
370      * @return this
371      */
372     public GridDataFactory grab(boolean horizontal, boolean vertical) {
373         data.grabExcessHorizontalSpace = horizontal;
374         data.grabExcessVerticalSpace = vertical;
375         return this;
376     }
377
378     /**
379      * Sets the minimum size for the control. The control will not be permitted
380      * to shrink below this size. Note: GridLayout treats a minimum size of 0
381      * as an undocumented special value, so the smallest possible minimum size
382      * is a size of 1. A minimum size of SWT.DEFAULT indicates that the result
383      * of computeSize(int, int, boolean) should be used as the control's minimum
384      * size.
385      *
386      *
387      * @param minX minimum a value of 1 or more is a horizontal size of the control (pixels).
388      * SWT.DEFAULT indicates that the control's preferred size should be used. A size
389      * of 0 has special semantics defined by GridLayout.
390      * @param minY minimum a value of 1 or more is a vertical size of the control (pixels). SWT.DEFAULT
391      * indicates that the control's preferred size should be used. A size
392      * of 0 has special semantics defined by GridLayout.
393      * @return this
394      */
395     public GridDataFactory minSize(int minX, int minY) {
396         data.minimumWidth = minX;
397         data.minimumHeight = minY;
398         return this;
399     }
400
401     /**
402      * Sets the minimum size for the control. The control will not be permitted
403      * to shrink below this size. Note: GridLayout treats a minimum size of 0
404      * as an undocumented special value, so the smallest possible minimum size
405      * is a size of 1. A minimum size of SWT.DEFAULT indicates that the result
406      * of computeSize(int, int, boolean) should be used as the control's minimum
407      * size.
408      *
409      * @param min minimum size of the control
410      * @return this
411      */
412     public GridDataFactory minSize(Point min) {
413         data.minimumWidth = min.x;
414         data.minimumHeight = min.y;
415         return this;
416     }
417
418     /**
419      * Instructs the GridLayout to ignore this control when performing layouts.
420      *
421      * @param shouldExclude true iff the control should be excluded from layouts
422      * @return this
423      */
424     public GridDataFactory exclude(boolean shouldExclude) {
425         data.exclude = shouldExclude;
426         return this;
427     }
428
429     /**
430      * Creates a new GridData instance. All attributes of the GridData instance
431      * will be initialized by the factory.
432      *
433      * @return a new GridData instance
434      */
435     public GridData create() {
436         return copyData(data);
437     }
438
439     /**
440      * Creates a copy of the reciever.
441      *
442      * @return a copy of the reciever
443      */
444     public GridDataFactory copy() {
445         return new GridDataFactory(create());
446     }
447     
448     /**
449      * Returns a copy of the given GridData
450      *
451      * @param data GridData to copy
452      * @return a copy of the argument
453      */
454     public static GridData copyData(GridData data) {
455         GridData newData = new GridData(data.horizontalAlignment, data.verticalAlignment, data.grabExcessHorizontalSpace, data.grabExcessVerticalSpace, data.horizontalSpan,
456                 data.verticalSpan);
457         newData.exclude = data.exclude;
458         newData.heightHint = data.heightHint;
459         newData.horizontalIndent = data.horizontalIndent;
460         newData.minimumHeight = data.minimumHeight;
461         newData.minimumWidth = data.minimumWidth;
462         newData.verticalIndent = data.verticalIndent;
463         newData.widthHint = data.widthHint;
464
465         return newData;
466     }
467
468     /**
469      * Sets the layout data on the given control. Creates a new GridData instance and
470      * assigns it to the control by calling control.setLayoutData.
471      *
472      * @param control control whose layout data will be initialized
473      */
474     public void applyTo(Control control) {
475         control.setLayoutData(create());
476     }
477
478 }
479
Popular Tags