Package com.luciad.lucy.gui

Class ALcyApplicationPaneTool

java.lang.Object
com.luciad.lucy.util.ALcyTool
com.luciad.lucy.gui.ALcyApplicationPaneTool
All Implemented Interfaces:
ILcdPropertyChangeSource
public abstract class ALcyApplicationPaneTool extends ALcyTool

Support class for writing an add-on that has an application pane. It takes care of these tasks:

  • It parses the application pane properties from the given properties, such as its title and default location.
  • It registers an active settable (=toggle action) in the configured action bars (e.g. menu bar) to activate and deactivate the application pane.
  • It handles workspace support.

Example properties (key=value) look like this (e.g. loaded from a configuration file using TLcyPreferencesTool): 


 # See ILcyApplicationPaneFactory.createApplicationPane for location
 shortPrefix.applicationPane.location = 2
 shortPrefix.applicationPane.appTitle = My title
 shortPrefix.applicationPane.smallIcon = icon/relative/to/classpath.png  # optional
 shortPrefix.applicationPane.shortDescription = My explanation           # optional

 # See developer's guide for detailed information on configuring menu items.
 shortPrefix.applicationPane.activeSettable.menuBar.item   = Tools, My menu item
 shortPrefix.applicationPane.activeSettable.menuBar.groups = ToolsGroup, DefaultGroup
 shortPrefix.applicationPane.activeSettable.menuBar.shortDescription = My panel description  # optional

Using this class in your add-on

You need to plug-in this tool when your add-on gets plugged in, and unplug it when your add-on gets unplugged: 

  public class MyAddOn extends ALcyPreferencesAddOn{
    private ALcyApplicationPaneTool fApplicationPaneTool;

    public MyAddOn() {
      super(ALcyTool.getLongPrefix(MyAddOn.class), ALcyTool.getShortPrefix(MyAddOn.class));
    }

    @Override
    public void plugInto(ILcyLucyEnv aLucyEnv) {
      super.plugInto(aLucyEnv);
      //Use the factory method to create the application pane tool
      fApplicationPaneTool = ALcyApplicationPaneTool.create(getPreferences(), getLongPrefix(), getShortPrefix(), this::createApplicationPaneContents);
      //Plug in the tool.
      //This will create the active settable and add it to the UI, and register the workspace codecs
      fApplicationPaneTool.plugInto(aLucyEnv);
    }

    private JComponent createApplicationPaneContents(){
      return new JLabel("Custom content");
    }

    @Override
    public void unplugFrom(ILcyLucyEnv aLucyEnv) {
      super.unplugFrom(aLucyEnv);
      //Unplug the tool again
      fApplicationPaneTool.unplugFrom(aLucyEnv);
    }
  }
In case you also need to perform clean-up tasks when the application pane gets removed, you can create an extension instead of using the create(ALcyProperties, String, String, Supplier) factory method and implement the applicationPaneDisposing() method. 

   ALcyApplicationPaneTool tool = new ALcyApplicationPaneTool(getPreferences(), getLongPrefix(), getShortPrefix()){
     @Override
     protected abstract Component createContent(){
       return createApplicationPaneContents();
     }

     @Override
     protected void applicationPaneDisposing() {
       //do your clean-up tasks here
     }
   }

When (not) to use this class

This class offers support for exactly one application pane, and must be plugged in when Lucy starts. This means that this class is perfect when you know exactly how many application panes you want to offer to the user:
  • Only a single application pane: you need to create one instance of this tool. The snippet in the section above illustrates how this can be done.
  • Multiple application panes: for each of the application panes, you need to create one instance of this tool. Note that each of these tools must use a unique long prefix.
This class cannot be used if the number of application panes is dynamic (for example one application pane for each map component).

Workspace support

This tool provides workspace support for the presence of the panel. When restoring a workspace where the panel was visible, this tool will re-create the application pane and use the createContent() method to restore the contents.

If your contents need to store some of its state in the workspace, you are responsible for doing this. In most cases this can be done by storing the state in the workspace preferences of your ALcyPreferencesAddOn. An example of this can be found in the "Adding extra panels" sample (see samples.lucy.applicationpane.ShowApplicationPaneAddOn and the corresponding article.

  • Constructor Details

    • ALcyApplicationPaneTool

      @Deprecated public ALcyApplicationPaneTool(ALcyProperties aProperties, Class aClass)
      Deprecated.
      Better use the constructor with explicit long and short prefix, to avoid any confusion. Functionally equivalent to ALcyApplicationPaneTool(aProperties, getLongPrefix(aClass), getShortPrefix(aClass)).
      Parameters:
      aProperties - The properties used to retrieve the settings from. Please refer to the class comment to see which property keys are used.
      aClass - A representative class for using this ALcyApplicationPaneTool, normally an extension of ALcyAddOn. It is used to retrieve the long and short prefixes using getLongPrefix and getShortPrefix. These prefixes are stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), the given class or its name must never change.
      See Also:

    • ALcyApplicationPaneTool

      public ALcyApplicationPaneTool(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix)
      Creates a new ALcyApplicationPaneTool. The properties are retrieved from the given properties.
      Parameters:
      aProperties - The properties used to retrieve the settings from. Please refer to the class comment to see which property keys are used.
      aLongPrefix - The long prefix. This prefix must be globally unique and must not be empty or null. It is stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change.
      aShortPrefix - The short prefix. This prefix is used to prefix the keys that are retrieved from the given properties (see class comment). It might be stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change.

  • Method Details

    • getProperties

      public ALcyProperties getProperties()
      Returns the ALcyProperties given at construction time.
      Returns:
      the ALcyProperties given at construction time.

    • getLongPrefix

      public String getLongPrefix()
      Returns the long prefix given at construction time.
      Returns:
      the long prefix given at construction time.

    • getShortPrefix

      public String getShortPrefix()
      Returns the short prefix given at construction time.
      Returns:
      the short prefix given at construction time.

    • getApplicationPane

      public ILcyApplicationPane getApplicationPane()
      Returns the current ILcyApplicationPane if it is active, or null when not active. An "applicationPane" PropertyChangeEvent is fired if this property changes.
      Returns:
      null, or the currently active ILcyApplicationPane.

    • isApplicationPaneActive

      public boolean isApplicationPaneActive()
      Returns true if there is currently an ILcyApplicationPane active for this ALcyApplicationPaneTool. An "applicationPaneActive" PropertyChangeEvent is fired if this property changes.
      Returns:
      True if the ILcyApplicationPane is active, false otherwise.
      See Also:

    • setApplicationPaneActive

      public void setApplicationPaneActive(boolean aApplicationPaneActive)
      Programmatically sets the ILcyApplicationPane to be active or not. Activating the ILcyApplicationPane results in getApplicationPane() to return a value different from null. De-activating the ILcyApplicationPane makes getApplicationPane return null.
      Parameters:
      aApplicationPaneActive - True to activate the ILcyApplicationPane, false to deactivate it.
      See Also:

    • plugInto

      public void plugInto(ILcyLucyEnv aLucyEnv)
      Description copied from class: ALcyTool

      Plugs this tool. This method is usually called from ALcyAddOn#plugInto.

      Overrides:
      plugInto in class ALcyTool
      Parameters:
      aLucyEnv - The environment to plug into.

    • unplugFrom

      public void unplugFrom(ILcyLucyEnv aLucyEnv)
      Description copied from class: ALcyTool

      Unplugs this tool. This method is usually called from ALcyAddOn#unplugFrom.

      Overrides:
      unplugFrom in class ALcyTool
      Parameters:
      aLucyEnv - The environment to unplug from, must be identical to the environment given to plugInto.

    • createContent

      protected abstract Component createContent()

      This method creates the content for the ILcyApplicationPane. It is added to the ILcyApplicationPane.getAppContentPane() in such a way that it stretches to use all available space.

      This method is called every time the ILcyApplicationPane is activated. Implementations are encouraged to create a new panel instance every time, although they can return the same instance for every call. The advantage of re-creating the content is that Look and Feel changes are handled automatically. If the same content is re-used, look and feel changes aren't handled automatically and implementations should best call JComponent.updateUI before returning the content. A side effect of re-creating the content is that any state is lost between activation and de-activation of the panel (e.g. selection). Therefore, if such state should be preserved, it should be stored elsewhere, for example in the associated properties.

      Returns:
      The content that will be put in the ILcyApplicationPane.

    • applicationPaneDisposing

      protected void applicationPaneDisposing()

      This method is called when disposing the application pane. The default implementation does nothing. Overwriting this method can be convenient to perform some cleanup tasks, such as removing listeners or setting unneeded references to null. When this method is called, getApplicationPane() still returns the application pane under disposal.

    • createApplicationPane

      protected ILcyApplicationPane createApplicationPane()
      Factory method to create the ILcyApplicationPane. Overwriting this method allows to create a different ILcyApplicationPane, or to fine tune the creation.
      Returns:
      The created ILcyApplicationPane.

    • create

      public static final ALcyApplicationPaneTool create(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix, Supplier<? extends Component> aContentsSupplier)
      Utility method to create a new ALcyApplicationPaneTool instance where the contents of the application pane is supplied by aContentsSupplier.
      Parameters:
      aProperties - The properties used to retrieve the settings from. Please refer to the class comment to see which property keys are used.
      aLongPrefix - The long prefix. This prefix must be globally unique and must not be empty or null. It is stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change.
      aShortPrefix - The short prefix. This prefix is used to prefix the keys that are retrieved from the given properties (see class comment). It might be stored in workspace files, so if backward compatibility is a concern (e.g. read an old workspace file), this prefix must never change.
      aContentsSupplier - The supplier for the contents of the application pane. This supplier is used to provide an implementation for the createContent() method.
      Consult the documentation of that method for more information on how that content is added to the application pane and what the advantages are of letting this supplier return a new instance each time it is called.
      When the supplied component implements ILcdDisposable, the dispose method will be called when the application pane is disposed.
      Returns:
      An application pane tool
      Since:
      2017.0