DefaultComponentFactory (JGoodies Forms 1.9 API)
Date: 2015-02-02

com.jgoodies.forms.factories

## Class DefaultComponentFactory

- java.lang.Object
- - com.jgoodies.forms.factories.DefaultComponentFactory

- All Implemented Interfaces:
    ComponentFactory

      public class DefaultComponentFactory
      extends Object
      implements ComponentFactory

  A singleton implementation of the `ComponentFactory` interface that creates UI components as required by the `FormBuilder`, `ListViewBuilder`, and other builders.

  The texts used in methods `#createLabel(String)` and `#createTitle(String)` can contain an optional mnemonic marker. The mnemonic and mnemonic index are indicated by a single ampersand (`&`). For example `"&Save"`, or `"Save &as"`. To use the ampersand itself duplicate it, for example `"Look&&Feel"`.

  Version:
    $Revision: 1.21 $
  Author:
    Karsten Lentzsch

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DefaultComponentFactory()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `JButton` | `createButton(Action action)` Creates and returns a button that is bound to the given Action.
    `JLabel` | `createHeaderLabel(String markedText)` Creates and returns a label intended for pane headers that uses a larger font than the control font and a special foreground color.
    `JLabel` | `createLabel(String textWithMnemonic)` Creates and returns a label with an optional mnemonic.
    `JLabel` | `createReadOnlyLabel(String textWithMnemonic)` Creates and returns a label with an optional mnemonic that is intended to label a read-only component.
    `JComponent` | `createSeparator(JLabel label)` Creates and returns a labeled separator.
    `JComponent` | `createSeparator(String textWithMnemonic)` Creates and returns a labeled separator with the label in the left-hand side.
    `JComponent` | `createSeparator(String textWithMnemonic, int alignment)` Creates and returns a labeled separator.
    `JLabel` | `createTitle(String textWithMnemonic)` Creates and returns a title label that uses the foreground color and font of a `TitledBorder`.
    `static DefaultComponentFactory` | `getInstance()` Returns the sole instance of this factory class.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultComponentFactory

          public DefaultComponentFactory()

  - ### Method Detail

    - #### getInstance

          public static DefaultComponentFactory getInstance()

      Returns the sole instance of this factory class.
      Returns:
        the sole instance of this factory class

    - #### createLabel

          public JLabel createLabel(String textWithMnemonic)

      Creates and returns a label with an optional mnemonic.

           createLabel("Name");       // No mnemonic
           createLabel("N&ame");      // Mnemonic is 'a'
           createLabel("Save &as");   // Mnemonic is the second 'a'
           createLabel("Look&&Feel"); // No mnemonic, text is Look&Feel

      Specified by:
        `createLabel` in interface `ComponentFactory`
      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        an label with optional mnemonic

    - #### createReadOnlyLabel

          public JLabel createReadOnlyLabel(String textWithMnemonic)

      Creates and returns a label with an optional mnemonic that is intended to label a read-only component.

           createReadOnlyLabel("Name");       // No mnemonic
           createReadOnlyLabel("N&ame");      // Mnemonic is 'a'
           createReadOnlyLabel("Save &as");   // Mnemonic is the second 'a'
           createReadOnlyLabel("Look&&Feel"); // No mnemonic, text is Look&Feel

      Specified by:
        `createReadOnlyLabel` in interface `ComponentFactory`
      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        an label with optional mnemonic intended for read-only components
      Since:
        1.3

    - #### createButton

          public JButton createButton(Action action)

      Creates and returns a button that is bound to the given Action. Useful to return customized buttons, for example, the JGoodies `JGButton` is bound to some custom Action properties.

      This default implementation just returns a `JButton`.

      Specified by:
        `createButton` in interface `ComponentFactory`
      Parameters:
        `action` - provides [bound] visual properties for the button
      Returns:
        the created button
      Since:
        1.4

    - #### createTitle

          public JLabel createTitle(String textWithMnemonic)

      Creates and returns a title label that uses the foreground color and font of a `TitledBorder`.

           createTitle("Name");       // No mnemonic
           createTitle("N&ame");      // Mnemonic is 'a'
           createTitle("Save &as");   // Mnemonic is the second 'a'
           createTitle("Look&&Feel"); // No mnemonic, text is Look&Feel

      Specified by:
        `createTitle` in interface `ComponentFactory`
      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        an emphasized title label

    - #### createHeaderLabel

          public JLabel createHeaderLabel(String markedText)

      Description copied from interface: `ComponentFactory`
      Creates and returns a label intended for pane headers that uses a larger font than the control font and a special foreground color. For example, on the Windows platform this method may use the font, size, and color of the TaskDialog main instruction as described by the MS User Experience Guide.

      If the label text is marked with the mnemonic marker '&', the mnemonic and mnemonic index will be configured. For example if `markedText` is "&Charge Codes", the text will be set to "Charge Codes", the mnemonic is 'C', and the mnemonic index is 0.

      A simple implementation may just delegate to `ComponentFactory.createTitle(String)`.

      Specified by:
        `createHeaderLabel` in interface `ComponentFactory`
      Parameters:
        `markedText` - the label text with optional mnemonic marker
      Returns:
        a label intended for pane headers

    - #### createSeparator

          public JComponent createSeparator(String textWithMnemonic)

      Creates and returns a labeled separator with the label in the left-hand side. Useful to separate paragraphs in a panel; often a better choice than a `TitledBorder`.

           createSeparator("Name");       // No mnemonic
           createSeparator("N&ame");      // Mnemonic is 'a'
           createSeparator("Save &as");   // Mnemonic is the second 'a'
           createSeparator("Look&&Feel"); // No mnemonic, text is Look&Feel

      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
      Returns:
        a title label with separator on the side

    - #### createSeparator

          public JComponent createSeparator(String textWithMnemonic,
                                   int alignment)

      Creates and returns a labeled separator. Useful to separate paragraphs in a panel, which is often a better choice than a `TitledBorder`.

           final int LEFT = SwingConstants.LEFT;
           createSeparator("Name",       LEFT); // No mnemonic
           createSeparator("N&ame",      LEFT); // Mnemonic is 'a'
           createSeparator("Save &as",   LEFT); // Mnemonic is the second 'a'
           createSeparator("Look&&Feel", LEFT); // No mnemonic, text is Look&Feel

      Specified by:
        `createSeparator` in interface `ComponentFactory`
      Parameters:
        `textWithMnemonic` - the label's text - may contain an ampersand (`&`) to mark a mnemonic
        `alignment` - text alignment, one of `SwingConstants.LEFT`, `SwingConstants.CENTER`, `SwingConstants.RIGHT`
      Returns:
        a separator with title label

    - #### createSeparator

          public JComponent createSeparator(JLabel label)

      Creates and returns a labeled separator. Useful to separate paragraphs in a panel, which is often a better choice than a `TitledBorder`.

      The label's position is determined by the label's horizontal alignment, which must be one of: `SwingConstants.LEFT`, `SwingConstants.CENTER`, `SwingConstants.RIGHT`.

      TODO: Since this method has been marked public in version 1.0.6, we need to precisely describe the semantic of this method.

      TODO: Check if we can relax the constraint for the label alignment and also accept LEADING and TRAILING.

      Parameters:
        `label` - the title label component
      Returns:
        a separator with title label
      Throws:
        `NullPointerException` - if the label is `null`
        `IllegalArgumentException` - if the label's horizontal alignment is not one of: `SwingConstants.LEFT`, `SwingConstants.CENTER`, `SwingConstants.RIGHT`.
      Since:
        1.0.6

Copyright © 2002-2015 JGoodies Software GmbH. All Rights Reserved.