Holger's Java API

## com.antelmann.util.gui
Class FormHelper

    java.lang.Object
      com.antelmann.util.gui.FormHelper

    public class FormHelper

extends Object

provides convenience to handle common problems when dealing with forms and has generally useful utility methods for handling form fields

Since:
  16.04.2010, 02:31:25
Author:
  Holger Antelmann

Field Summary
`static String` `COMMIT_VALUE_KEY` used to fire a `PropertyChangeEvent` that will directly commit a value

Constructor Summary
`FormHelper()`

Method Summary
`void` `bind(JComponent field, Object obj, String property, Runnable runOnUpdate, String changePropertyKey)`
`JComponent` `createBoundField(Object obj, String property, Runnable runOnUpdate)`
`JComponent` `createComponentFor(Class<?> c)` creates and returns a component suitable for editing objects of the given class.
`static String` `enterMessage(Component parent, String title)` opens a dialog allowing to enter a multi-line message
`static String` `enterMessage(Component parent, String title, boolean resizable)` opens a dialog allowing to enter a multi-line message
`static String` `enterMessage(Component parent, String title, int rows, int columns)` opens a dialog allowing to enter a multi-line message
`static String` `enterMessage(Component parent, String title, int rows, int columns, boolean resizable, int optionType)` opens a dialog allowing to enter a multi-line message
`static String` `enterMessage(Component parent, String title, int rows, int columns, boolean resizable, int optionType, Filter<String> filter, String initialValue)` opens a dialog allowing to enter a multi-line message
`static Number` `enterNumber(Component parent, String title, Object message)`
`static Number` `enterNumber(Component parent, String title, Object message, NumberFormat format, Filter<? super Number> filter, Object initialValue)`
`static char[]` `enterPassword(Component parent)` returns null on cancel
`static char[]` `enterPassword(Component parent, String title, Object message, char[] initialValue)` returns null on cancel
`static char[]` `enterPassword(Component parent, String title, Object message, char[] initialValue, ImageIcon icon)` returns null on cancel; tries to set caps lock to false to avoid common mistakes
`static String` `enterString(Component parent, String title, Object message, Filter<String> filter, Object initialValue)`

`static

`<T> T`

`

`extractInterface(Component component, Class<T> type)`

`protected Method` `findMethod(Class<?> type, String name)`
`static void` `fixTabKeys(Component... cs)` enables the standard tab keys for focus traversal.
`static Object` `getFormValue(Form form, Object defaultValue, String dialogTitle)`
`static Object` `getFormValue(Form form, ValueRetriever<?> retriever, String dialogTitle)` convenience method that allows to retrieve a value from a form if applicable
`Number` `getNumberFor(JComponent field)` returns 0 if the field could not be parsed as a number (or was null)
`static String` `getText(JTextComponent comp)` convenience method - returns actually null if the component text is either empty or contains only whitespace
`Object` `getValueFor(JComponent field)` allows to specialize the way how the value for the given key is retrieved from the given component.
`void` `installChangeListener(Component comp, Runnable r)`
`void` `installChangeListener(Component comp, Runnable r, String changeProperty)`
`void` `installChangeListener(Component comp, Task<? extends RuntimeException> task)` this method creates and installs listeners for the given component that run the given task upon changes to the component
`void` `installChangeListener(Component comp, Task<? extends RuntimeException> task, String changeProperty)` additionally supports the option to use a `PropertyChangeListener` with the given property if everything else fails.
`void` `installChangeListener(Runnable r, Component... cs)`
`static boolean` `isNotEmpty(String str)`
`static void` `limitSize(JTextComponent c, DBClassStore<?> store, String column)`
`static void` `limitSize(JTextComponent c, int chars)` limits the number of characters that can be entered into the given text component.
`static void` `limitSize(JTextComponent c, MappingInfo mi, String column)`
`static String` `nullForEmpty(String str)`
`void` `setEditable(boolean flag, Component... comp)`
`void` `setEditable(Component c, boolean flag)`
`void` `setValueFor(Object value, JComponent field)` applies the given value to the given component.

`static

`<T> T`

`

`showSelectDialog(Component parent, String title, Component selectionComp, ValueRetriever<T> retriever, boolean resizable)`
shows a dialog that lets you select a value with the given selectionComp and then retrieves the selected value via the given retriever.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### COMMIT_VALUE_KEY

    public static final String COMMIT_VALUE_KEY

  used to fire a `PropertyChangeEvent` that will directly commit a value

  See Also:
    `showSelectDialog(Component, String, Component, ValueRetriever, boolean)`, Constant Field Values

Constructor Detail

### FormHelper

    public FormHelper()

Method Detail

### showSelectDialog

    public static <T> T showSelectDialog(Component parent,
                                         String title,
                                         Component selectionComp,
                                         ValueRetriever<T> retriever,
                                         boolean resizable)

  shows a dialog that lets you select a value with the given selectionComp and then retrieves the selected value via the given retriever. This method uses a `PropertyChangeListener` on the selectionComp to react on selection changes so that the dialog can update the 'ok'-button accordingly. If you want to support a directly committed selection within the selectionComp then simply fire a `PropertyChangeEvent` with the property name `COMMIT_VALUE_KEY`. The selectionComp will receive the initial focus when the component is displayed.

  Parameters:
    `parent` - the parent component determining where the dialog is to be located
    `title` - the title of the dialog displayed
    `selectionComp` - the component that allows to select a value; this component should fire a `PropertyChangeEvent` upon selection changes. Also, this component will get the focus via `Component.requestFocusInWindow()`, so make sure the given component acts appropriately to this call.
    `retriever` - provides a way for this method to retrieve the selected value from the component
    `resizable` - determines whether the dialog is to be resizable
  Returns:
    the value that was selected through the given component or null if the dialog was cancelled
  See Also:
    `Component.requestFocusInWindow()`, `COMMIT_VALUE_KEY`

### enterNumber

    public static Number enterNumber(Component parent,
                                     String title,
                                     Object message)

### enterNumber

    public static Number enterNumber(Component parent,
                                     String title,
                                     Object message,
                                     NumberFormat format,
                                     Filter<? super Number> filter,
                                     Object initialValue)

### enterString

    public static String enterString(Component parent,
                                     String title,
                                     Object message,
                                     Filter<String> filter,
                                     Object initialValue)

### enterMessage

    public static String enterMessage(Component parent,
                                      String title)

  opens a dialog allowing to enter a multi-line message

### enterMessage

    public static String enterMessage(Component parent,
                                      String title,
                                      boolean resizable)

  opens a dialog allowing to enter a multi-line message

### enterMessage

    public static String enterMessage(Component parent,
                                      String title,
                                      int rows,
                                      int columns)

  opens a dialog allowing to enter a multi-line message

### enterMessage

    public static String enterMessage(Component parent,
                                      String title,
                                      int rows,
                                      int columns,
                                      boolean resizable,
                                      int optionType)

  opens a dialog allowing to enter a multi-line message

### enterMessage

    public static String enterMessage(Component parent,
                                      String title,
                                      int rows,
                                      int columns,
                                      boolean resizable,
                                      int optionType,
                                      Filter<String> filter,
                                      String initialValue)

  opens a dialog allowing to enter a multi-line message

### enterPassword

    public static char[] enterPassword(Component parent)

  returns null on cancel

### enterPassword

    public static char[] enterPassword(Component parent,
                                       String title,
                                       Object message,
                                       char[] initialValue)

  returns null on cancel

### enterPassword

    public static char[] enterPassword(Component parent,
                                       String title,
                                       Object message,
                                       char[] initialValue,
                                       ImageIcon icon)

  returns null on cancel; tries to set caps lock to false to avoid common mistakes

### getText

    public static String getText(JTextComponent comp)

  convenience method - returns actually null if the component text is either empty or contains only whitespace

### fixTabKeys

    public static void fixTabKeys(Component... cs)

  enables the standard tab keys for focus traversal. This is particularly useful for a JTextArea or a JTable in a dialog form component.

### limitSize

    public static void limitSize(JTextComponent c,
                                 int chars)
                          throws ClassCastException

  limits the number of characters that can be entered into the given text component.

  Throws:
    `ClassCastException` - if the component's document is not an AbstractDocument
  See Also:
    `DocumentSizeFilter`

### limitSize

    public static void limitSize(JTextComponent c,
                                 DBClassStore<?> store,
                                 String column)

### limitSize

    public static void limitSize(JTextComponent c,
                                 MappingInfo mi,
                                 String column)

### createComponentFor

    public JComponent createComponentFor(Class<?> c)

  creates and returns a component suitable for editing objects of the given class. This implementation supports `String` (via `JTextField`), `Number` (via `JFormattedTextField`), `Boolean` (via `JCheckBox`), `Color` (via `JColorChooser`), `File` (via `JFileField`), and `Date` (via `JTimeChooser`); others are simply handled via `JTextField`.

  See Also:
    `setValueFor(Object, JComponent)`, `getValueFor(JComponent)`

### getNumberFor

    public Number getNumberFor(JComponent field)
                        throws IllegalArgumentException

  returns 0 if the field could not be parsed as a number (or was null)

  Throws:
    `IllegalArgumentException`

### createBoundField

    public JComponent createBoundField(Object obj,
                                       String property,
                                       Runnable runOnUpdate)
                                throws IllegalArgumentException

  Throws:
    `IllegalArgumentException`
  See Also:
    `bind(JComponent, Object, String, Runnable, String)`

### bind

    public void bind(JComponent field,
                     Object obj,
                     String property,
                     Runnable runOnUpdate,
                     String changePropertyKey)
              throws IllegalArgumentException

  Throws:
    `IllegalArgumentException`

### findMethod

    protected Method findMethod(Class<?> type,
                                String name)

### getValueFor

    public Object getValueFor(JComponent field)
                       throws IllegalArgumentException

  allows to specialize the way how the value for the given key is retrieved from the given component. This implementation ignores the key parameter and just retrieves the value from the supported components.

  Throws:
    `IllegalArgumentException` - if the given keyField is not supported
  See Also:
    `JCheckBox`, `JComboBox`, `JSpinner`, `JFormattedTextField`, `JTextComponent`, `JSlider`, `JColorChooser`, `ValueRetriever`

### setValueFor

    public void setValueFor(Object value,
                            JComponent field)
                     throws IllegalArgumentException,
                            ClassCastException

  applies the given value to the given component. This implementation supports the same components as `getValueFor(JComponent)` plus `ValueSetter`.

  Throws:
    `IllegalArgumentException`
    `ClassCastException`

### setEditable

    public void setEditable(boolean flag,
                            Component... comp)

### setEditable

    public void setEditable(Component c,
                            boolean flag)

### installChangeListener

    public void installChangeListener(Runnable r,
                                      Component... cs)

### installChangeListener

    public void installChangeListener(Component comp,
                                      Runnable r)

### installChangeListener

    public void installChangeListener(Component comp,
                                      Task<? extends RuntimeException> task)
                               throws IllegalArgumentException

  this method creates and installs listeners for the given component that run the given task upon changes to the component

  Throws:
    `IllegalArgumentException` - if the given component is not supported for this task

### installChangeListener

    public void installChangeListener(Component comp,
                                      Runnable r,
                                      String changeProperty)

### installChangeListener

    public void installChangeListener(Component comp,
                                      Task<? extends RuntimeException> task,
                                      String changeProperty)
                               throws IllegalArgumentException

  additionally supports the option to use a `PropertyChangeListener` with the given property if everything else fails.

  Parameters:
    `changeProperty` - the change property to be used as a fallback solution - provided it's non-null
  Throws:
    `IllegalArgumentException`

### extractInterface

    public static <T> T extractInterface(Component component,
                                         Class<T> type)

### getFormValue

    public static Object getFormValue(Form form,
                                      Object defaultValue,
                                      String dialogTitle)
                               throws IOException

  Throws:
    `IOException`

### getFormValue

    public static Object getFormValue(Form form,
                                      ValueRetriever<?> retriever,
                                      String dialogTitle)
                               throws IOException

  convenience method that allows to retrieve a value from a form if applicable

  Parameters:
    `form` - the form to be queried for the value if the form is indeed dirty
    `retriever` - retrieves the value to be used if the form is either not given or not dirty
    `dialogTitle` - the title to be used in the dialog when asked to save changes
  Returns:
    the committed value of the form if the given form was dirty or the given defaultValue otherwise; null is returned if the form was dirty and the dialog was canceled.
  Throws:
    `IOException`
  See Also:
    `Form.performSaveAction()`, `Form.isDirty()`

### nullForEmpty

    public static String nullForEmpty(String str)

### isNotEmpty

    public static boolean isNotEmpty(String str)

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads