GridLayoutFactory


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   *     Karsten Stoeckmann - bug 156982
12   *******************************************************************************/
13  package org.eclipse.jface.layout;
14  import org.eclipse.swt.graphics.Point;
15  import org.eclipse.swt.graphics.Rectangle;
16  import org.eclipse.swt.layout.GridLayout;
17  import org.eclipse.swt.widgets.Composite;
18  
19  /**
20   * GridLayoutFactory creates and initializes grid layouts. There are two ways to use GridLayoutFactory.
21   * Normally, it is used as a shorthand for writing "new GridLayout()" and initializing a bunch 
22   * of fields. In this case the main benefit is a more concise syntax and the ability to create more
23   * than one identical GridLayout from the same factory. Changing a property of the factory will affect
24   * future layouts created by the factory, but has no effect on layouts that have already been created.
25   * 
26   * <p>
27   * GridLayoutFactory can also generate grid data for all the controls in a layout. This is done with
28   * the generateLayout method. To use this feature:
29   * </p>
30   * 
31   * <ol>
32   * <li>Create the composite</li>
33   * <li>Create all the controls in the composite</li>
34   * <li>Call generateLayout</li>
35   * </ol>
36   * 
37   * <p>
38   * The order here is important. generateLayout must be called after all the child controls have
39   * been created. generateLayout will not change any layout data that has already been attached
40   * to a child control and it will not recurse into nested composites. 
41   * </p>
42   *
43   * @since 3.2
44   */
45  public final class GridLayoutFactory {
46      
47      /**
48       * Template layout. The factory will create copies of this layout. 
49       */
50      private GridLayout l;
51  
52      /**
53       * Creates a new GridLayoutFactory that will create copies of the given layout.
54       * 
55       * @param l layout to copy
56       */
57      private GridLayoutFactory(GridLayout l) {
58          this.l = l;
59      }
60  
61      /**
62       * Creates a factory that creates copies of the given layout.
63       * 
64       * @param l layout to copy
65       * @return a new GridLayoutFactory instance that creates copies of the given layout
66       */
67      public static GridLayoutFactory createFrom(GridLayout l) {
68          return new GridLayoutFactory(copyLayout(l));
69      }
70      
71      /**
72       * Creates a copy of the reciever.
73       * 
74       * @return a copy of the reciever
75       */
76      public GridLayoutFactory copy() {
77          return new GridLayoutFactory(create());
78      }
79      
80      /**
81       * Creates a GridLayoutFactory that creates GridLayouts with the default SWT
82       * values.
83       * 
84       * <p>
85       * Initial values are:
86       * </p>
87       * 
88       * <ul>
89       * <li>numColumns(1)</li>
90       * <li>margins(5,5)</li>
91       * <li>extendedMargins(0,0,0,0)</li>
92       * <li>spacing(5,5)</li>
93       * <li>equalWidth(false)</li>
94       * </ul>
95       * 
96       * @return a GridLayoutFactory that creates GridLayouts as though created with
97       * their default constructor
98       * @see #fillDefaults
99       */
100     public static GridLayoutFactory swtDefaults() {
101         return new GridLayoutFactory(new GridLayout());
102     }
103 
104     /**
105      * Creates a GridLayoutFactory that creates GridLayouts with no margins and 
106      * default dialog spacing.
107      * 
108      * <p>
109      * Initial values are:
110      * </p>
111      * 
112      * <ul>
113      * <li>numColumns(1)</li>
114      * <li>margins(0,0)</li>
115      * <li>extendedMargins(0,0,0,0)</li>
116      * <li>spacing(LayoutConstants.getSpacing())</li>
117      * <li>equalWidth(false)</li>
118      * </ul>
119      * 
120      * @return a GridLayoutFactory that creates GridLayouts as though created with
121      * their default constructor
122      * @see #swtDefaults
123      */
124     public static GridLayoutFactory fillDefaults() {
125         GridLayout layout = new GridLayout();
126         layout.marginWidth = 0;
127         layout.marginHeight = 0;
128         Point defaultSpacing = LayoutConstants.getSpacing();
129         layout.horizontalSpacing = defaultSpacing.x;
130         layout.verticalSpacing = defaultSpacing.y;
131         return new GridLayoutFactory(layout);
132     }
133     
134     /**
135      * Sets whether the columns should be forced to be equal width
136      * 
137      * @param equal true iff the columns should be forced to be equal width
138      * @return this
139      */
140     public GridLayoutFactory equalWidth(boolean equal) {
141         l.makeColumnsEqualWidth = equal;
142         return this;
143     }
144 
145     /**
146      * Sets the spacing for layouts created with this factory. The spacing
147      * is the distance between cells within the layout. 
148      * 
149      * @param hSpacing horizontal spacing (pixels)
150      * @param vSpacing vertical spacing (pixels)
151      * @return this
152      * @see #margins(Point)
153      * @see #margins(int, int)
154      */
155     public GridLayoutFactory spacing(int hSpacing, int vSpacing) {
156         l.horizontalSpacing = hSpacing;
157         l.verticalSpacing = vSpacing;
158         return this;
159     }
160 
161     /**
162      * Sets the spacing for layouts created with this factory. The spacing
163      * is the distance between cells within the layout. 
164      * 
165      * @param spacing space between controls in the layout (pixels)
166      * @return this
167      * @see #margins(Point)
168      * @see #margins(int, int)
169      */
170     public GridLayoutFactory spacing(Point spacing) {
171         l.horizontalSpacing = spacing.x;
172         l.verticalSpacing = spacing.y;
173         return this;
174     }
175 
176     /**
177      * Sets the margins for layouts created with this factory. The margins
178      * are the distance between the outer cells and the edge of the layout.
179      * 
180      * @param margins margin size (pixels)
181      * @return this
182      * @see #spacing(Point)
183      * @see #spacing(int, int)
184      */
185     public GridLayoutFactory margins(Point margins) {
186         l.marginWidth = margins.x;
187         l.marginHeight = margins.y;
188         return this;
189     }
190 
191     /**
192      * Sets the margins for layouts created with this factory. The margins
193      * specify the number of pixels of horizontal and vertical margin that will
194      * be placed along the left/right and top/bottom edges of the layout. Note
195      * that thes margins will be added to the ones specified by
196      * {@link #extendedMargins(int, int, int, int)}.
197      * 
198      * @param width
199      *            margin width (pixels)
200      * @param height
201      *            margin height (pixels)
202      * @return this
203      * @see #spacing(Point)
204      * * @see #spacing(int, int)
205      */
206     public GridLayoutFactory margins(int width, int height) {
207         l.marginWidth = width;
208         l.marginHeight = height;
209         return this;
210     }
211 
212     /**
213      * Sets the margins for layouts created with this factory. The margins
214      * specify the number of pixels of horizontal and vertical margin that will
215      * be placed along the left, right, top, and bottom edges of the layout.
216      * Note that thes margins will be added to the ones specified by
217      * {@link #margins(int, int)}.
218      * 
219      * @param left
220      *            left margin size (pixels)
221      * @param right
222      *            right margin size (pixels)
223      * @param top
224      *            top margin size (pixels)
225      * @param bottom
226      *            bottom margin size (pixels)
227      * @return this
228      * @see #spacing(Point)
229      * @see #spacing(int, int)
230      * 
231      * @since 3.3
232      */
233     public GridLayoutFactory extendedMargins(int left, int right, int top, int bottom) {
234         l.marginLeft = left;
235         l.marginRight = right;
236         l.marginTop = top;
237         l.marginBottom = bottom;
238         return this;
239     }
240 
241     /**
242      * Sets the margins for layouts created with this factory. The margins
243      * specify the number of pixels of horizontal and vertical margin that will
244      * be placed along the left, right, top, and bottom edges of the layout.
245      * Note that thes margins will be added to the ones specified by
246      * {@link #margins(int, int)}.
247      * 
248      * <code><pre>
249      *     // Construct a GridLayout whose left, right, top, and bottom 
250      *     // margin sizes are 10, 5, 0, and 15 respectively
251      *      
252      *     Rectangle margins = Geometry.createDiffRectangle(10,5,0,15);
253      *     GridLayoutFactory.fillDefaults().extendedMargins(margins).applyTo(composite1);
254      * </pre></code>
255      * 
256      * @param differenceRect rectangle which, when added to the client area of the
257      *        layout, returns the outer area of the layout. The x and y values of
258      *        the rectangle correspond to the position of the bounds of the 
259      *        layout with respect to the client area. They should be negative. 
260      *        The width and height correspond to the relative size of the bounds
261      *        of the layout with respect to the client area, and should be positive. 
262      * @return this
263      * @see #spacing(Point)
264      * @see #spacing(int, int)
265      * 
266      * @since 3.3
267      */
268     public GridLayoutFactory extendedMargins(Rectangle differenceRect) {
269         l.marginLeft = -differenceRect.x;
270         l.marginTop = -differenceRect.y;
271         l.marginBottom = differenceRect.y + differenceRect.height;
272         l.marginRight = differenceRect.x + differenceRect.width;
273         return this;
274     }
275     
276     /**
277      * Sets the number of columns in the layout
278      * 
279      * @param numColumns number of columns in the layout
280      * @return this
281      */
282     public GridLayoutFactory numColumns(int numColumns) {
283         l.numColumns = numColumns;
284         return this;
285     }
286 
287     /**
288      * Creates a new GridLayout, and initializes it with values from the factory.
289      * 
290      * @return a new initialized GridLayout.
291      * @see #applyTo
292      */
293     public GridLayout create() {
294         return copyLayout(l);
295     }
296 
297     /**
298      * Creates a new GridLayout and attaches it to the given composite.
299      * Does not create the GridData of any of the controls in the composite.
300      * 
301      * @param c composite whose layout will be set
302      * @see #generateLayout
303      * @see #create
304      * @see GridLayoutFactory
305      */
306     public void applyTo(Composite c) {
307         c.setLayout(copyLayout(l));
308     }
309 
310     /**
311      * Copies the given GridLayout instance
312      * 
313      * @param l layout to copy
314      * @return a new GridLayout
315      */
316     public static GridLayout copyLayout(GridLayout l) {
317         GridLayout result = new GridLayout(l.numColumns, l.makeColumnsEqualWidth);
318         result.horizontalSpacing = l.horizontalSpacing;
319         result.marginBottom = l.marginBottom;
320         result.marginHeight = l.marginHeight;
321         result.marginLeft = l.marginLeft;
322         result.marginRight = l.marginRight;
323         result.marginTop = l.marginTop;
324         result.marginWidth = l.marginWidth;
325         result.verticalSpacing = l.verticalSpacing;
326 
327         return result;
328     }
329 
330     /**
331      * Applies this layout to the given composite, and attaches default GridData
332      * to all immediate children that don't have one. The layout is generated using 
333      * heuristics based on the widget types. In most cases, it will create exactly the same
334      * layout that would have been hardcoded by the programmer. In any situation
335      * where it does not produce the desired layout, the GridData for any child can be 
336      * overridden by attaching the layout data before calling this method. In these cases,
337      * the special-case layout data can be hardcoded and the algorithm can supply defaults
338      * to the rest.
339      * 
340      * <p>
341      * This must be called <b>AFTER</b> all of the child controls have been created and their
342      * layouts attached. This method will attach a layout to the given composite. If any new 
343      * children are created after calling this method, their GridData must be created manually. 
344      * The algorithm does not recurse into child composites. To generate all the layouts in
345      * a widget hierarchy, the method must be called bottom-up for each Composite.   
346      * </p>
347      * 
348      * <p>
349      * All controls are made to span a single cell. The algorithm tries to classify controls into one 
350      * of the following categories:
351      * </p>
352      * 
353      * <ul>
354      * <li>Pushbuttons: Set to a constant size large enough to fit their text and no smaller
355      * than the default button size.</li>
356      * <li>Wrapping with text (labels, read-only text boxes, etc.): override the preferred horizontal 
357      *     size with the default wrapping point, fill horizontally, grab horizontal space, keep the
358      *     preferred vertical size</li>
359      * <li>Wrapping without text (toolbars, coolbars, etc.): fill align, don't grab, use the preferred size</li>
360      * <li>Horizontally scrolling controls (anything with horizontal scrollbars or where the user edits
361      *     text and can cursor through it from left-to-right): override the preferred horizontal size with
362      *     a constant, grab horizontal, fill horizontal.</li>
363      * <li>Vertically scrolling controls (anything with vertical scrollbars or where the user edits
364      *     text and can cursor through it up and down): override the preferred vertical size with a constant,
365      *     grab vertical, fill vertical</li>
366      * <li>Nested layouts: fill align both directions, grab along any dimension if the layout would
367      *     be able to expand along that dimension.</li>
368      * <li>Non-wrapping non-scrollable read-only text: fill horizontally, center vertically, default size, don't grab </li>
369      * <li>Non-wrapping non-scrollable non-text: fill both, default size, don't grab</li>
370      * </ul>
371      * 
372      * @param c composite whose layout will be generated
373      */
374     public void generateLayout(Composite c) {
375         applyTo(c);
376         LayoutGenerator.generateLayout(c);
377     }
378 }
379
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags