Package com.luciad.lucy.gui.customizer

Class ALcyCustomizerPanel

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
com.luciad.lucy.gui.customizer.ALcyCustomizerPanel
All Implemented Interfaces:
ILcdUndoableSource, ILcyCustomizerPanel, ILcdPropertyChangeSource, ImageObserver, MenuContainer, Serializable, Accessible
Direct Known Subclasses:
ALcyDataPropertyCustomizerPanel, ALcyDomainObjectCustomizerPanel, ALcyLayerCustomizerPanel, ALcyModelCustomizerPanel, ALcyShapeCustomizerPanel
public abstract class ALcyCustomizerPanel extends JPanel implements ILcyCustomizerPanel

Abstract implementation of ILcyCustomizerPanel that provides default implementations for most methods of the interface.

What it provides:

  • It stores the key-value pairs.
  • It keeps the collections of listeners.
  • It manages the "changesPending" events; extensions only have to invoke setChangesPending(true) when the user has made some changes. When applyChanges or cancelChanges is called, the "changesPending" property is automatically reset to false.

What is left for the extensions of this class:

While this class is a general-purpose base-class for ILcyCustomizerPanel implementations, there are several subclasses that are geared towards more specific use-cases, such as customizing domain objects, layers or models.

See Also:

  • Constructor Details

    • ALcyCustomizerPanel

      protected ALcyCustomizerPanel(ILcdFilter aObjectFilter)
      Constructs a new ALcyCustomizerPanel.
      Parameters:
      aObjectFilter - The ILcdFilter that defines which objects are accepted by canSetObject and setObject. See also setPaintState.

    • ALcyCustomizerPanel

      protected ALcyCustomizerPanel(ILcdFilter aObjectFilter, String aName)
      Constructs a new ALcyCustomizerPanel.
      Parameters:
      aObjectFilter - The ILcdFilter that defines which objects are accepted by canSetObject and setObject. See also setObjectFilter.
      aName - The name for this ALcyCustomizerPanel, see ILcyCustomizerPanel.NAME.

    • ALcyCustomizerPanel

      protected ALcyCustomizerPanel(ILcdFilter aObjectFilter, String aName, ILcdIcon aSmallIcon)
      Constructs a new ALcyCustomizerPanel.
      Parameters:
      aObjectFilter - The ILcdFilter that defines which objects are accepted by canSetObject and setObject. See also setPaintState.
      aName - The name for this ALcyCustomizerPanel, see ILcyCustomizerPanel.NAME.
      aSmallIcon - The small icon of this ALcyCustomizerPanel, see ILcyCustomizerPanel.SMALL_ICON.

    • ALcyCustomizerPanel

      protected ALcyCustomizerPanel(ILcdFilter aObjectFilter, String aName, ILcdIcon aSmallIcon, String aShortDescription)
      Constructs a new ALcyCustomizerPanel.
      Parameters:
      aObjectFilter - The ILcdFilter that defines which objects are accepted by canSetObject and setObject. See also setPaintState.
      aName - The name for this ALcyCustomizerPanel, see ILcyCustomizerPanel.NAME.
      aSmallIcon - The small icon of this ALcyCustomizerPanel, see ILcyCustomizerPanel.SMALL_ICON.
      aShortDescription - The short description of this ALcyCustomizerPanel, see ILcyCustomizerPanel.SHORT_DESCRIPTION.

  • Method Details

    • setName

      public void setName(String name)

      Note: if you want to adjust the display name of this customizer panel, you need to use the putValue(String, Object) method with ILcyCustomizerPanel.NAME as key. Consult the documentation of that constant for more information.

      Overrides:
      setName in class Component

    • getValue

      public Object getValue(String aKey)
      Description copied from interface: ILcyCustomizerPanel
      Gets the property value for the given key.
      Specified by:
      getValue in interface ILcyCustomizerPanel
      Parameters:
      aKey - The key to retrieve the value for.
      Returns:
      the property value for the given key.
      See Also:

    • putValue

      public void putValue(String aKey, Object aValue)
      Description copied from interface: ILcyCustomizerPanel
      Sets the property value for aKey to aValue. If the value has changed, a PropertyChangeEvent is sent to the listeners. The property name of the event equals the value of aKey.
      Specified by:
      putValue in interface ILcyCustomizerPanel
      Parameters:
      aKey - The key. Should preferably start with an uppercase letter to avoid confusion with regular properties.
      aValue - The value.
      See Also:

    • getObjectFilter

      public ILcdFilter getObjectFilter()
      Returns the object filter.
      Returns:
      The object filter. It may be null.
      See Also:

    • setObjectFilter

      public void setObjectFilter(ILcdFilter aObjectFilter)
      Sets the object filter. The filter is used by setObject and canSetObject to determine which objects should be accepted and which should be rejected. If the filters accept method returns true, canSetObject also returns true.

      The object given to the filters accept method is guaranteed to be not null, as null is always accepted: it deinitialises the ILcyCustomizerPanel.

      Parameters:
      aObjectFilter - The object filter. This may be null. In that case, all objects will be accepted.

    • isChangesPending

      public boolean isChangesPending()
      Returns true if changes are pending. A change is a modification made by the user, e.g., the modified content of a text field. Pending means the method applyChanges was not invoked after the change occurred.

      A property change event "changesPending" must be fired if the return value of this method is changed. This can for example be used to enable/disable an apply button.

      The default value for this implementation is false.

      Specified by:
      isChangesPending in interface ILcyCustomizerPanel
      Returns:
      true if there are pending changes, false otherwise.

    • setChangesPending

      protected void setChangesPending(boolean aChangesPending)

      Sets if there are any outstanding changes in the user interface. Fires a "changesPending" property change event if the value has changed.

      This method has protected access as only extensions of this class should invoke setChangesPending(true) whenever the user has made changes in the user interface that are waiting to be committed.

      Extension of this class can invoke setChangesPending(false) when the user undoes any changes. For instance, the user could have checked a checkbox previously, and unchecked it later, in which case this property can be restored to false. Whenever the changes are applied or canceled, this property is automatically set to false.

      Parameters:
      aChangesPending - true when there are outstanding changes, false otherwise.
      See Also:

    • isChangesValid

      public boolean isChangesValid()
      Returns true if the pending changes are valid, or if there are no pending changes. Returns false if there are invalid pending changes. A change is a modification made by the user, e.g., the modified content of a text field. Pending means the method applyChanges was not invoked after the change occurred.

      False could for example be returned if the user has entered invalid input that cannot be applied, such as text where a number is expected.

      A property change event "changesValid" must be fired if the return value of this method is changed. This can for example be used to enable/disable an apply button, or to inform the user that he must first correct the invalid content.

      Implementations can ignore this feature by always returning true.

      The default value for this implementation is true.

      Specified by:
      isChangesValid in interface ILcyCustomizerPanel
      Returns:
      true.

    • setChangesValid

      protected void setChangesValid(boolean aChangesValid)

      Sets if changes are valid. Fires a "changesValid" property change event if the value has changed.

      This method has protected access as only extensions of this class should invoke setChangesValid(false) whenever the user has made changes in the user interface that are invalid, such as entering text where a number is expected.

      Extension of this class can invoke setChangesValid(true) when the user undoes any invalid changes, by making them valid again. For instance, when the user replaces some text with some number where that is expected.

      Note that setting this property is optional as the default value is true, which allows to apply any pending changes. The implementation of apply can then, for example, revert any invalid changes.

      Parameters:
      aChangesValid - true if the pending changes are valid (or if there are no changes), false otherwise.
      See Also:

    • canSetObject

      public boolean canSetObject(Object aObject)
      Returns true if and only if setObject would not throw an IllegalArgumentException.

      Only accepts null or objects that pass the object filter. If the filter itself is null, all objects are accepted.

      Specified by:
      canSetObject in interface ILcyCustomizerPanel
      Parameters:
      aObject - The object to check.
      Returns:
      true if setObject would accept the object, false if it would throw an exception.

    • setObject

      public void setObject(Object aObject)
      Set the object to be edited. This method should be called before the ILcyCustomizerPanel has been added to any parent AWT container. It can be called afterwards as well however. In this case the user interface should update itself to represent the newly set object.

      A value of null is set to inform this ILcyCustomizerPanel to (temporarily) deinitialize itself, it allows to perform cleanup tasks, such as removing listeners. Invokes updateCustomizerPanelFromObject() to update the user interface.

      Specified by:
      setObject in interface ILcyCustomizerPanel
      Parameters:
      aObject - The object to be customized, or null to inform that editing is temporarily disabled.

    • getObject

      public Object getObject()
      Returns the object that was set using setObject.
      Specified by:
      getObject in interface ILcyCustomizerPanel
      Returns:
      the object that was set using setObject. Can be null if this customizer panel was deinitialized.
      See Also:

    • addUndoableListener

      public void addUndoableListener(ILcdUndoableListener aUndoableListener)
      Description copied from interface: ILcdUndoableSource
      Adds a listener to this source, so this listener is notified when something undoable has happened.
      Specified by:
      addUndoableListener in interface ILcdUndoableSource
      Parameters:
      aUndoableListener - The listener to be notified when something undoable has happened.

    • removeUndoableListener

      public void removeUndoableListener(ILcdUndoableListener aUndoableListener)
      Description copied from interface: ILcdUndoableSource
      Removes the specified listener so it is no longer notified.
      Specified by:
      removeUndoableListener in interface ILcdUndoableSource
      Parameters:
      aUndoableListener - The listener to remove.

    • fireUndoableHappened

      protected final void fireUndoableHappened(ILcdUndoable aUndoable)
      Fires the given ILcdUndoable to all associated ILcdUndoableListeners. Extensions of this class should use this method if they want to support undo/redo.
      Parameters:
      aUndoable - The ILcdUndoable to fire. All registered ILcdUndoableListener instances will be notified of this undoable.

    • applyChanges

      public boolean applyChanges()
      Updates the set Object according to the current state of the user interface. This means all pending changes are committed.

      If there were any pending changes, so isChangesPending returned true, it should return false after this method has finished, and therefore also a "changesPending" property change event must be fired.

      E.g. consider that a ILcdGXYLayer object is set and a new label text is entered in a text field. When this method is called, the new label text should be set to the ILcdGXYLayer (using ILcdGXYLayer.setLabel).

      This implementation invokes applyChangesImpl() and sets the "changesPending" property. As a result, the "changesPending" event is fired when needed.

      Specified by:
      applyChanges in interface ILcyCustomizerPanel
      Returns:
      True if the changes were applied or if there were no changes, false if the changes could not be applied because they are invalid. In that event, isChangesValid returns false.
      See Also:

    • cancelChanges

      public void cancelChanges()
      Updates the user interface state according to the current state of the set Object. Any changes that were made in the user interface but were not yet applied, should be discarded.

      E.g. consider that an ILcdGXYLayer is being edited and a new label text was entered in a text field. When this method is called, the new label text should be cleared and the current label of the ILcdGXYLayer should be put in the text field (ILcdGXYLayer.getLabel()).

      This implementation invokes updateCustomizerPanelFromObject() and sets the "changesPending" property to false. As a result, the "changesPending" event is fired when needed.

      Specified by:
      cancelChanges in interface ILcyCustomizerPanel
      See Also:

    • applyChangesImpl

      protected abstract boolean applyChangesImpl()

      Apply any pending changes. This method should do the same as applyChanges(), except that it should not take care of "changesPending".

      Returns:
      True if changes could be applied or if there were no changes, false otherwise. Please refer to applyChanges() for more detailed information.

    • updateCustomizerPanelFromObject

      protected abstract void updateCustomizerPanelFromObject()

      Updates the user interface state according to the current state of the set Object. This method is called whenever a new object is set using setObject, or when the changes are canceled using cancelChanges.

      It does not need to take care of "changesPending".

      Consider for example that a TLcyLayerContext is set and a new label text is entered in a text field. When this method is called, the new label text should be cleared and the original label of the ILcdLayer (getLabel()) should be put in the text field.