Interface ComponentManager

  • All Known Implementing Classes:
    ComponentManagerWrapper

    public interface ComponentManager

    Definition of an interface to a concrete GUI manager.

    The form framework tries to be independent of a specific GUI technology like Swing or SWT. Instead widgets are addressed in a generic way, as objects. This interface defines accessor methods for such generic GUI objects. Concrete implementation classes will map these methods onto an existing GUI library.

    The most important client for this interface is the form builder jelly tag library. The tags represent generic form elements, e.g. labels, text fields or radio buttons. Concrete implementations for these elements are created through interface methods. This makes it possible to plug in different GUI libraries. So one and the same jelly script could once create a Swing GUI and another time an SWT GUI.

    A large part of the methods defined in this interface deal with the creation of GUI components. Those components are wrapped into a ComponentHandler implementation, which makes it possible to add them to a Form object and to access their data. Some of these methods have a boolean argument create. During the processing of the Jelly script that defines the GUI they are called twice, once with the argument set to true and once with the argument set to false. The first call comes before the tag's body is evaluated, the second after that. This allows for different ways of constructing component hierarchies (e.g. in Swing components are added to containers using an add() of the container, SWT on the other hand requires the container being passed into the component's constructor - thus the container must have been created prior than the component.

    Additional methods are responsible for creating auxiliary objects, like icons, fonts or layout constraints, or for manipulating container objects, which can contain other GUI elements.

    Note: This interface is not intended to be directly implemented by client code. It is subject to change even in minor releases as new features are made available. Therefore if an application needs to provide a custom implementation of this interface, it should extend an existing implementation. For instance, the ComponentManagerWrapper class is a good candidate if only a subset of methods is to be modified.

    Version:
    $Id: ComponentManager.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    • Method Detail

      • addContainerComponent

        void addContainerComponent​(Object container,
                                   Object component,
                                   Object constraints)
        Adds a component to a container using the specified constraints. This method is called to populate container objects.
        Parameters:
        container - the container
        component - the component which is to be added to the container
        constraints - a generic constraints object; this object must be compatible with the layout manager set for the container; it may be null
      • setContainerLayout

        void setContainerLayout​(Object container,
                                Object layout)
        Defines the layout manager for a container.
        Parameters:
        container - the container
        layout - the new layout manager
      • createEventManager

        PlatformEventManager createEventManager()
        Returns a concrete implementation of the PlatformEventManager interface for dealing with event notifications. This method is called once when the event handling features are used for the first time.
        Returns:
        the platform specific event manager
      • getWidgetHandlerFor

        WidgetHandler getWidgetHandlerFor​(Object component)
        Returns a WidgetHandler for the specified component. This method is called by ComponentBuilderData when the user asks for a handler to a certain component. The passed in object is one of the components that was created during the last builder operation. An implementation may throw a runtime exception if a widget handler for the passed in component cannot be obtained.
        Parameters:
        component - the component
        Returns:
        a WidgetHandler wrapping the specified component
      • createLabel

        Object createLabel​(LabelTag tag,
                           boolean create)
                    throws FormBuilderException
        Creates a label object. All needed properties are extracted from the passed in tag.
        Parameters:
        tag - the label tag
        create - the create flag
        Returns:
        the new label
        Throws:
        FormBuilderException - if an error occurs
      • linkLabel

        void linkLabel​(Object label,
                       Object component,
                       String text)
                throws FormBuilderException
        Associates a link with another component. This method will be called if the componentref attribute of a LabelTag was used to define a link between a lable and another component. An implementation will have to use library specific methods to establish such a connection. Eventually the label's text has to be set to the given text (this is the case if the label is undefined; its text is then obtained from the component's display name).
        Parameters:
        label - the label (as returned by the createLabel() method
        component - the component to be linked to the label
        text - an optional text to be set for the label; can be null, then no text has to be set
        Throws:
        FormBuilderException - if an error occurs
      • createIcon

        Object createIcon​(Locator locator)
                   throws FormBuilderException
        Creates an icon object with the data obtained from the specified Locator
        Parameters:
        locator - the Locator pointing to the data
        Returns:
        the new icon object
        Throws:
        FormBuilderException - if an error occurs
      • createPercentLayout

        Object createPercentLayout​(PercentLayoutTag tag)
                            throws FormBuilderException
        Creates a percent layout object whose parameters are obtained from the specified tag.
        Parameters:
        tag - the percent layout tag
        Returns:
        the new layout object
        Throws:
        FormBuilderException - if an error occurs
      • createButtonLayout

        Object createButtonLayout​(ButtonLayoutTag tag)
                           throws FormBuilderException
        Creates a button layout object whose parameters are obtained from the specified tag.
        Parameters:
        tag - the button layout tag
        Returns:
        the new layout object
        Throws:
        FormBuilderException - if an error occurs
      • createBorderLayout

        Object createBorderLayout​(BorderLayoutTag tag)
                           throws FormBuilderException
        Creates a border layout object whose parameters are obtained form the specified tag.
        Parameters:
        tag - the border layout tag
        Returns:
        the new layout object
        Throws:
        FormBuilderException - if an error occurs
      • createPanel

        Object createPanel​(PanelTag tag,
                           boolean create)
                    throws FormBuilderException
        Creates a panel whose parameters are obtained from the specified tag.
        Parameters:
        tag - the panel tag
        create - the create flag
        Returns:
        the new panel object
        Throws:
        FormBuilderException - if an error occurs
      • createDesktopPanel

        Object createDesktopPanel​(DesktopPanelTag tag,
                                  boolean create)
                           throws FormBuilderException
        Creates a desktop panel whose parameters are obtained from the specified tag. The desktop panel can be used as basic background for MDI child windows.
        Parameters:
        tag - the desktop panel tag
        create - the create flag
        Returns:
        the new desktop panel object
        Throws:
        FormBuilderException - if an error occurs
      • createSplitter

        Object createSplitter​(SplitterTag tag,
                              boolean create)
                       throws FormBuilderException
        Creates a splitter whose parameters are obtained from the specified tag.
        Parameters:
        tag - the splitter tag
        create - the create flag
        Returns:
        the new splitter component
        Throws:
        FormBuilderException - if an error occurs
      • createRadioGroup

        Object createRadioGroup​(Map<String,​Object> radioButtons)
                         throws FormBuilderException
        Creates a radio group which contains the radio buttons stored in the passed in map. Radio groups are treated as non visual components that merely implement the radio logic. They will not be inserted into a GUI container. The passed in map contains the names of the radio buttons as keys and the corresponding component objects as values.
        Parameters:
        radioButtons - a map with the radio button components that belong to the group
        Returns:
        the new radio group
        Throws:
        FormBuilderException - if an error occurs
      • createButton

        ComponentHandler<Boolean> createButton​(ButtonTag tag,
                                               boolean create)
                                        throws FormBuilderException
        Creates a button component. All needed properties are extracted from the passed in tag. Buttons (or to be more precise: command buttons) are considered as input components though they do not gather user input. The reason for this is that the event mechanism is coupled to ComponentHandler instances, so for a button to generate events there must be an associated component handler. Note that the returned component handler is usually not added to the generated Form object. If the button really should be used as input component, its data is a boolean value indicating whether the button is selected (which makes sense if the button is used as a toggle button).
        Parameters:
        tag - the button tag
        create - the create flag
        Returns:
        the component handler for the new button
        Throws:
        FormBuilderException - if an error occurs
      • createToggleButton

        ComponentHandler<Boolean> createToggleButton​(ToggleButtonTag tag,
                                                     boolean create)
                                              throws FormBuilderException
        Creates a toggle button component. A toggle button is a simple switch that can be selected (pressed) or not. So the data associated with components of this type is simply a boolean.
        Parameters:
        tag - the tag defining the toggle button
        create - the create flag
        Returns:
        the component handler for the new toggle button
        Throws:
        FormBuilderException - if an error occurs
      • createTextField

        ComponentHandler<String> createTextField​(TextFieldTag tag,
                                                 boolean create)
                                          throws FormBuilderException
        Creates a component handler that wraps a text field. The data type of this handler is String.
        Parameters:
        tag - the tag defining the text field
        create - the create flag
        Returns:
        the component handler for the text field
        Throws:
        FormBuilderException - if an error occurs
      • createTextArea

        ComponentHandler<String> createTextArea​(TextAreaTag tag,
                                                boolean create)
                                         throws FormBuilderException
        Creates a component handler that wraps a text area. The data type of this handler is String.
        Parameters:
        tag - the tag defining the text area
        create - the create flag
        Returns:
        the component handler for the text area
        Throws:
        FormBuilderException - if an error occurs
      • createPasswordField

        ComponentHandler<String> createPasswordField​(PasswordFieldTag tag,
                                                     boolean create)
                                              throws FormBuilderException
        Creates a ComponentHandler that wraps a password text field. This handler acts like a regular handler for text input fields. Only the visual representation is different because the characters typed by the user in the text field are not readable.
        Parameters:
        tag - the tag defining the password text field
        create - the create flag
        Returns:
        the ComponentHandler for the password text field
        Throws:
        FormBuilderException - if an error occurs
      • createCheckbox

        ComponentHandler<Boolean> createCheckbox​(CheckboxTag tag,
                                                 boolean create)
                                          throws FormBuilderException
        Creates a component handler that wraps a checkbox. This handler's data is of type boolean.
        Parameters:
        tag - the tag defining the checkbox
        create - the create flag
        Returns:
        the component handler for the checkbox
        Throws:
        FormBuilderException - if an error occurs
      • createRadioButton

        ComponentHandler<Boolean> createRadioButton​(RadioButtonTag tag,
                                                    boolean create)
                                             throws FormBuilderException
        Creates a component handler that wraps a radio button. This handler's data is of type boolean.
        Parameters:
        tag - the tag defining the radio button
        create - the create flag
        Returns:
        the component handler for the radio button
        Throws:
        FormBuilderException - if an error occurs
      • createComboBox

        ComponentHandler<Object> createComboBox​(ComboBoxTag tag,
                                                boolean create)
                                         throws FormBuilderException
        Creates a component handler that wraps a combo box. This handler maintains a single data object of the same type as the combo box's list model.
        Parameters:
        tag - the tag defining the combo box
        create - the create flag
        Returns:
        the component handler for the combo box
        Throws:
        FormBuilderException - if an error occurs
      • createListBox

        ComponentHandler<Object> createListBox​(ListBoxTag tag,
                                               boolean create)
                                        throws FormBuilderException
        Creates a component handler that wraps a list box. This handler's data type is based on the type of the list's model and on the list's multi selection flag: for a single selection list the type is the same as the list's model's type, for a multi selection list it is an array of this type.
        Parameters:
        tag - the tag defining the list box
        create - the create flag
        Returns:
        the component handler for the list box
        Throws:
        FormBuilderException - if an error occurs
      • createTabbedPane

        ComponentHandler<Integer> createTabbedPane​(TabbedPaneTag tag,
                                                   boolean create)
                                            throws FormBuilderException
        Creates a component handler that wraps a tabbed pane. The handler's data consists of a single Integer object, which represents the (0-based) index of the selected tab. It can be read and set.
        Parameters:
        tag - the tag defining the tabbed pane
        create - the create flag
        Returns:
        the component handler for the tabbed pane
        Throws:
        FormBuilderException - if an error occurs
      • createStaticText

        ComponentHandler<StaticTextData> createStaticText​(StaticTextTag tag,
                                                          boolean create)
                                                   throws FormBuilderException
        Creates a component handler that wraps a static text element. The handler's data consists of a StaticTextData object, which can be used to read and write the static text's properties. The returned handler can be casted into a StaticTextHandler object; the additional methods defined by this interface can be used to directly set the key properties of the static text component.
        Parameters:
        tag - the tag defining the static text
        create - the create flag
        Returns:
        the component handler for the static text
        Throws:
        FormBuilderException - if an error occurs
      • createProgressBar

        ComponentHandler<Integer> createProgressBar​(ProgressBarTag tag,
                                                    boolean create)
                                             throws FormBuilderException
        Creates a component handler that wraps a progress bar element. The handler's data is an integer value representing the current position of the progress bar. The handler can be casted into a ProgressBarHandler object; the additional methods defined by this interface can be used to manipulate further properties of the progress bar.
        Parameters:
        tag - the tag defining the progress bar
        create - the create flag
        Returns:
        the component handler for the progress bar
        Throws:
        FormBuilderException - if an error occurs
      • createSlider

        ComponentHandler<Integer> createSlider​(SliderTag tag,
                                               boolean create)
                                        throws FormBuilderException
        Creates a component handler that wraps a slider component. The handler's data is an integer value representing the current value of the slider.
        Parameters:
        tag - the tag defining the slider
        create - the create flag
        Returns:
        the component handler for the slider
        Throws:
        FormBuilderException - if an error occurs
      • createTable

        ComponentHandler<Object> createTable​(TableTag tag,
                                             boolean create)
                                      throws FormBuilderException
        Creates a table based on the information stored in the passed in table tag. This is a complex operation because it has to be ensured that the table is fully initialized. It is guaranteed that the tag contains only valid data. The table's data model, its columns, and form objects to be used for rendering or editing cells are available. The returned ComponentHandler object wraps the table component. It can be casted into a TableHandler object. Its data depends on the selection type of the table: in single selection mode it is the index of the selected row; in multi selection mode it is an int[] with the indices of the selected rows. By registering a change listener at the returned ComponentHandler interested components can be notified when the table's selection changes.
        Parameters:
        tag - the table tag
        create - the create flag
        Returns:
        the component handler for the new table component
        Throws:
        FormBuilderException - if an error occurs
      • createTree

        ComponentHandler<Object> createTree​(TreeTag tag,
                                            boolean create)
                                     throws FormBuilderException
        Creates a tree component based on the information stored in the passed in tree tag. The tag has been fully initialized, it especially contains the model to be used for the tree. The ComponentHandler returned by this method can be casted into a TreeHandler object. Refer to the documentation of this class for more information about the data supported by this handler.
        Parameters:
        tag - the tree tag
        create - the create flag
        Returns:
        the component handler for the new tree component
        Throws:
        FormBuilderException - if an error occurs