LayoutSupportDelegate


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  
20  package org.netbeans.modules.form.layoutsupport;
21  
22  import java.awt.*;
23  import java.beans.*;
24  import org.openide.nodes.*;
25  import org.netbeans.modules.form.codestructure.*;
26  
27  /**
28   * Main interface for working with various layouts of visual containers
29   * in Form Editor. An implementations of this interface should hold some
30   * metadata representing the layout, be able to set up live components and
31   * containers (according to the metadata), handle code generation and
32   * persistence, provide drag&drop and resizing support, etc.
33   * This interface is very general, it is not recommended to implement it
34   * directly. There is a default implementation - AbstractLayoutSupport - which
35   * provides most of the necessary functionality, assuming that the supported
36   * layout works with certain patterns and rules.
37   *
38   * @see LayoutConstraints
39   * @see LayoutSupportContext
40   *
41   * @author Tomas Pavek
42   */
43  
44  public interface LayoutSupportDelegate {
45  
46      /** Bit flag indicating possible component resizing in upper direction. */
47      final int RESIZE_UP = 1;
48      /** Bit flag indicating possible component resizing in down direction. */
49      final int RESIZE_DOWN = 2;
50      /** Bit flag indicating possible component resizing in left direction. */
51      final int RESIZE_LEFT = 4;
52      /** Bit flag indicating possible component resizing in right direction. */
53      final int RESIZE_RIGHT = 8;
54  
55      /** Initialization of the layout delegate before the first use.
56       * There are three types of initialization which must be supported:
57       * (1) default initialization for an empty (newly created) layout
58       *    (lmInstance == null, fromCode == false),
59       * (2) initialization from an already existing instance of LayoutManager
60       *    (lmInstance != null, fromCode == false),
61       * (3) initialization from persistent code structure,
62       *    (lmInstance == null, fromCode == true).
63       * @param layoutContext provides a necessary context information for the
64       *                      layout delegate
65       * @param lmInstance LayoutManager instance for initialization (may be null)
66       * @param fromCode indicates whether to initialize from code structure
67       * @exception any Exception occurred during initialization
68       */
69      void initialize(LayoutSupportContext layoutContext,
70                      LayoutManager lmInstance,
71                      boolean fromCode)
72          throws Exception  ;
73  
74      /** Gets the supported layout manager or container class. Container class
75       * is returned if the delegate is "dedicated" to some special container
76       * rather than to a layout manager used generally for any container.
77       * @return the class supported by this delegate
78       * @see isDedicated method
79       */
80      Class   getSupportedClass();
81  
82      /** States whether this delegate class is dedicted to some special
83       * container layout.
84       * @return true if the delegates supports just certain container only,
85       *         false if the delegates supports a layout manager for use in
86       *               any container
87       * @see getSupportedClass method
88       */
89      boolean isDedicated();
90  
91      /** For dedicated supports: check whether given default container instance
92       * is empty.
93       * @param cont default instance of Container
94       * @return true if the container can be used as default (empty) instance
95       *         with this layout support
96       */
97      boolean checkEmptyContainer(Container cont);
98  
99      /** Indicates whether the layout should be presented as a node in Component
100      * Inspector (for setting properties). The node is provided for layout
101      * managers typically (except null layou), and not for dedicated containers
102      * support.
103      * @return whether a node should be created for the layout
104      */
105     boolean shouldHaveNode();
106 
107     /** Provides a localized display name for the layout node (to be used in
108      * Component Inspector and Palette).
109      * @return display name of supported layout
110      */
111     String   getDisplayName();
112 
113     /** Provides an icon to be used for the layout node in Component
114      * Inspector. Only 16x16 color icon is required.
115      * @param type is one of BeanInfo constants: ICON_COLOR_16x16,
116      *        ICON_COLOR_32x32, ICON_MONO_16x16, ICON_MONO_32x32
117      * @return icon to be displayed for node in Component Inspector,
118      *         null if no icon is provided
119      */
120     Image getIcon(int type);
121 
122     /** This method returns properties of the supported layout (so of some
123      * LayoutManager implementation class typically). These properties are
124      * editable by the user in Component Inspector when layout node is
125      * selected. These are not properties of individual component constraints
126      * (see LayoutConstraints.getProperties() for that).
127      * @return properties of supported layout
128      */
129     Node.PropertySet[] getPropertySets();
130 
131     /** Returns a class of a customizer for the layout manager being used as
132      * a JavaBean. The class should be a java.awt.Component and
133      * java.beans.Customizer. Such a customizer is usually provided with the
134      * layout bean itself, specified in BeanInfo class. When the customizer is
135      * to be used, it is instantiated and given the reference layout manager
136      * instance (using Customizer.setObject(...) method).
137      * Note: If the layout delegate provides special customizer from
138      * getSupportCustomizer() method, it should still return its class here so
139      * it is apparent that there is some customizer provided.
140      * @return layout customizer class, null if no customizer is provided
141      */
142     Class   getCustomizerClass();
143 
144     /** Returns an instance of a special customizer provided by the layout
145      * delegate. This customizer need not implement java.beans.Customizer,
146      * because its creation is under full control of the layout delegate - and
147      * vice versa, the customizer can have full control over the layout
148      * delegate (unlike the bean customizer which operates only with layout
149      * manager bean instance).
150      * Note: If the layout delegate provides the customizer here, the class of
151      * the customizer should be also returned from getCustomizerClass() method.
152      * @return instance of layout support customizer
153      */
154     Component getSupportCustomizer();
155 
156     /** Gets the complete code for setting up the layout (including adding
157      * components).
158      * @return whole container's layout code
159      */
160     CodeGroup getLayoutCode();
161 
162     /** Gets code for setting up one component's constraints and adding the
163      * component to the layout (container).
164      * @return one component's layout code
165      */
166     CodeGroup getComponentCode(int index);
167 
168     /** Gets CodeExpression object representing one component.
169      * @param index index of the component in the layout
170      * @return CodeExpression for a component
171      */
172     CodeExpression getComponentCodeExpression(int index);
173 
174     /** Gets number of components in the layout.
175      * @return number of components in the layout
176      */
177     int getComponentCount();
178 
179     /** This method is called to accept new components before they are added
180      * to the layout (by calling addComponents method). It may adjust the
181      * constraints, or refuse the components by throwing a RuntimeException
182      * (e.g. IllegalArgumentException). It's up to the delagate to display an
183      * error or warning message, the exception is not reported outside.
184      * To accept any components simply do nothing here.
185      * @param compExpressions array of CodeExpression objects representing the
186      *        components to be accepted
187      * @param constraints array of layout constraints of the components, may
188      *        contain nulls
189      * @param index position at which the components are to be added (inserted);
190      *        -1 means that the components will be added at the end
191      * @exception RunTimeException to refuse components
192      */
193     void acceptNewComponents(CodeExpression[] compExpressions,
194                              LayoutConstraints[] constraints,
195                              int index);
196 
197     /** This method is called after a property of the layout is changed by
198      * the user. The delagate implementation may check whether the layout is
199      * valid after the change and throw PropertyVetoException if the change
200      * should be reverted. It's up to the delagate to display an error or
201      * warning message, the exception is not reported outside. To accept any
202      * changes simply do nothing here.
203      * @param ev PropertyChangeEvent object describing the change
204      */
205     void acceptContainerLayoutChange(PropertyChangeEvent ev)
206         throws PropertyVetoException;
207 
208     /** This method is called after a constraint property of some component
209      * is changed by the user. The delegate implementation may check if the
210      * layout is valid after the change and throw PropertyVetoException if the
211      * change should be reverted. It's up to the delagate to display an error
212      * or warning message, the exception is not reported outside. To accept
213      * any changes simply do nothing here.
214      * @param index index of the component in the layout
215      * @param ev PropertyChangeEvent object describing the change
216      */
217     void acceptComponentLayoutChange(int index, PropertyChangeEvent ev)
218         throws PropertyVetoException;
219 
220     /** Adds new components to the layout. (This is intended just at the
221      * metadata level, no real components are added in fact.)
222      * @param compExpressions array of CodeExpression objects representing the
223      *        components to be added
224      * @param constraints array of layout constraints of the components, may
225      *        contain nulls
226      * @param index position at which the components should be added (inserted);
227      *        if -1, the components should be added at the end
228      */
229     void addComponents(CodeExpression[] compExpressions,
230                        LayoutConstraints[] constraints,
231                        int index);
232 
233     /** Removes one component from the layout (at metadata level).
234      * @param index index of the component in the layout
235      */
236     void removeComponent(int index);
237 
238     /** Removes all components from the layout (at metadata level).
239      */
240     void removeAll();
241 
242     /** Indicates whether there's some change in the layout in comparison
243      * with the default layout of given container. If there's no change, no
244      * code needs to be delegate (e.g. default FlowLayout in JPanel).
245      * Note this is related to the container layout only, not to components.
246      * @param defaultContainer instance of the default container to compare with
247      * @param defaultContainerDelegate effective container delegate of the
248      *        default container (e.g. like content pane of JFrame)
249      * @return whether the current layout is different from the default one
250      */
251     boolean isLayoutChanged(Container defaultContainer,
252                             Container defaultContainerDelegate);
253 
254     /** Gets layout constraints for a component at the given index.
255      * @param index index of the component in the layout
256      * @return layout constraints of given component
257      */
258     LayoutConstraints getConstraints(int index);
259 
260     /** This method is called when switching layout - giving an opportunity to
261      * convert the previous constrainst of components to constraints of the new
262      * layout (this layout). This method needs to do nothing if there's no
263      * reasonable conversion possible (addComponents method receives null
264      * constraints then).
265      * @param previousConstraints [input] layout constraints of components in
266      *                                    the previous layout
267      * @param currentConstraints [output] array of converted constraints for
268      *                                    the new layout - to be filled
269      * @param components [input] real components in a real container having the
270      *                           previous layout
271      */
272     void convertConstraints(LayoutConstraints[] previousConstraints,
273                             LayoutConstraints[] currentConstraints,
274                             Component[] components);
275 
276     /** Sets up the layout (without adding components) on a real container,
277      * according to the internal metadata representation.
278      * @param container instance of a real container to be set
279      * @param containerDelegate effective container delegate of the container
280      *        (e.g. like content pane of JFrame)
281      */
282     void setLayoutToContainer(Container container,
283                               Container containerDelegate);
284 
285     /** Adds real components to given container (according to layout
286      * constraints stored for the components).
287      * @param container instance of a real container to be added to
288      * @param containerDelegate effective container delegate of the container
289      *        (e.g. like content pane of JFrame)
290      * @param components components to be added
291      * @param index position at which to add the components to container
292      */
293     void addComponentsToContainer(Container container,
294                                   Container containerDelegate,
295                                   Component[] components,
296                                   int index);
297 
298     /** Removes a real component from a real container.
299      * @param container instance of a real container
300      * @param containerDelegate effective container delegate of the container
301      *        (e.g. like content pane of JFrame)
302      * @param component component to be removed
303      * @return whether it was possible to remove the component (some containers
304      *         may not support removing individual components reasonably)
305      */
306     boolean removeComponentFromContainer(Container container,
307                                          Container containerDelegate,
308                                          Component component);
309 
310     /** Removes all components from given real container.
311      * @param container instance of a real container to be cleared
312      * @param containerDelegate effective container delegate of the container
313      *        (e.g. like content pane of JFrame)
314      * @return whether it was possible to clear the container (some containers
315      *         may not support this)
316      */
317     boolean clearContainer(Container container, Container containerDelegate);
318 
319     /** This method is called when user clicks on the container in form
320      * designer. The layout delegate may do something with the container,
321      * e.g. for JTabbedPane it might switch the selected TAB.
322      * @param p Point of click in the container
323      * @param real instance of the container when the click occurred
324      * @param containerDelegate effective container delegate of the container
325      *        (e.g. like content pane of JFrame)
326      */
327     void processMouseClick(Point p,
328                            Container container,
329                            Container containerDelegate);
330 
331     /** This method is called when a component is selected in Component
332      * Inspector. If the layout delegate is interested in such information,
333      * it should store it and use it e.g. in arrangeContainer method.
334      * @param index position (index) of the selected component in container
335      */
336     void selectComponent(int index);
337 
338     /** In this method, the layout delegate has a chance to "arrange" real
339      * container instance additionally - some other way that cannot be
340      * done through layout properties and added components. For example, the
341      * selected component index can be applied here (see delegates for
342      * CardLayout and JTabbedPane).
343      * @param container instance of a real container to be arranged
344      * @param containerDelegate effective container delegate of the container
345      *        (e.g. like content pane of JFrame)
346      */
347     void arrangeContainer(Container container, Container containerDelegate);
348 
349     /** This method should calculate layout constraints for a component dragged
350      * over a container (or just for mouse cursor being moved over container,
351      * without any component). This method is useful for "constraints oriented"
352      * layout managers (like e.g. BorderLayout or GridBagLayout).
353      * @param container instance of a real container over/in which the
354      *        component is dragged
355      * @param containerDelegate effective container delegate of the container
356      *        (e.g. like content pane of JFrame)
357      * @param component the real component being dragged, can be null
358      * @param index position (index) of the component in its container;
359      *        -1 if there's no dragged component
360      * @param posInCont position of mouse in the container delegate
361      * @param posInComp position of mouse in the dragged component; null if
362      *        there's no dragged component
363      * @return new LayoutConstraints object corresponding to the position of
364      *         the component in the container; may return null if the layout
365      *         does not use component constraints, or if default constraints
366      *         should be used
367      */
368     LayoutConstraints getNewConstraints(Container container,
369                                         Container containerDelegate,
370                                         Component component,
371                                         int index,
372                                         Point posInCont,
373                                         Point posInComp);
374 
375     /** This method should calculate position (index) for a component dragged
376      * over a container (or just for mouse cursor being moved over container,
377      * without any component). This method is useful for layout managers that
378      * don't use component constraints (like e.g. FlowLayout or GridLayout)
379      * @param container instance of a real container over/in which the
380      *        component is dragged
381      * @param containerDelegate effective container delegate of the container
382      *        (e.g. like content pane of JFrame)
383      * @param component the real component being dragged, can be null
384      * @param index position (index) of the component in its container;
385      *        -1 if there's no dragged component
386      * @param posInCont position of mouse in the container delegate
387      * @param posInComp position of mouse in the dragged component; null if
388      *        there's no dragged component
389      * @return index corresponding to the position of the component in the
390      *         container; may return -1 if the layout rather uses component
391      *         constraints, or if a default index should be used
392      */
393     int getNewIndex(Container container,
394                     Container containerDelegate,
395                     Component component,
396                     int index,
397                     Point posInCont,
398                     Point posInComp);
399 
400     /** This method should paint a feedback for a component dragged over
401      * a container (or just for mouse cursor being moved over container,
402      * without any component). In principle, it should present given component
403      * layout constraints or index graphically.
404      * @param container instance of a real container over/in which the
405      *        component is dragged
406      * @param containerDelegate effective container delegate of the container
407      *        (e.g. like content pane of JFrame) - here the feedback is painted
408      * @param component the real component being dragged, can be null
409      * @param newConstraints component layout constraints to be presented
410      * @param newIndex component's index position to be presented
411      *        (if newConstraints == null)
412      * @param g Graphics object for painting (with color and line style set)
413      * @return whether any feedback was painted (may return false if the
414      *         constraints or index are invalid, or if the painting is not
415      *         implemented)
416      */
417     boolean paintDragFeedback(Container container, 
418                               Container containerDelegate,
419                               Component component,
420                               LayoutConstraints newConstraints,
421                               int newIndex,
422                               Graphics g);
423 
424     /** Provides resizing options for given component. It can combine the
425      * bit-flag constants RESIZE_UP, RESIZE_DOWN, RESIZE_LEFT, RESIZE_RIGHT.
426      * @param container instance of a real container in which the
427      *        component is to be resized
428      * @param containerDelegate effective container delegate of the container
429      *        (e.g. like content pane of JFrame)
430      * @param component real component to be resized
431      * @param index position of the component in its container
432      * @return resizing options for the component; 0 if no resizing is possible
433      */
434     int getResizableDirections(Container container,
435                                Container containerDelegate,
436                                Component component,
437                                int index);
438 
439     /** This method should calculate layout constraints for a component being
440      * resized.
441      * @param container instance of a real container in which the
442      *        component is resized
443      * @param containerDelegate effective container delegate of the container
444      *        (e.g. like content pane of JFrame)
445      * @param component real component being resized
446      * @param index position of the component in its container
447      * @param originalBounds original bounds of the resized component.
448      * @param sizeChanges Insets object with size differences
449      * @param posInCont position of mouse in the container delegate
450      * @return component layout constraints for resized component; null if
451      *         resizing is not possible or not implemented
452      */
453     LayoutConstraints getResizedConstraints(Container container,
454                                             Container containerDelegate,
455                                             Component component,
456                                             int index,
457                                             Rectangle originalBounds,
458                                             Insets sizeChanges,
459                                             Point posInCont);
460 
461     /** Cloning method - creates a copy of the layout delegate.
462      * @param targetContext LayoutSupportContext for the new layout delegate
463      * @param compExpressions array of CodeExpression objects representing the
464      *        components for the new layout delegate (corresponding to the
465      *        current ones)
466      * @return cloned layout delegate instance
467      */
468     LayoutSupportDelegate cloneLayoutSupport(LayoutSupportContext targetContext,
469                                              CodeExpression[] targetComponents);
470 }
471
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags