public abstract class ALcyApplicationPaneTool extends ALcyTool
Support class for writing an add-on that has an application pane. It takes care of these tasks:
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
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
}
}
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 and Description |
---|
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)) . |
ALcyApplicationPaneTool(ALcyProperties aProperties,
String aLongPrefix,
String aShortPrefix)
Creates a new
ALcyApplicationPaneTool . |
Modifier and Type | Method and Description |
---|---|
protected void |
applicationPaneDisposing()
This method is called when disposing the application pane.
|
static 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 . |
protected ILcyApplicationPane |
createApplicationPane()
Factory method to create the
ILcyApplicationPane . |
protected abstract Component |
createContent()
This method creates the content for the
ILcyApplicationPane . |
ILcyApplicationPane |
getApplicationPane()
Returns the current
ILcyApplicationPane if it is active, or null when not active. |
String |
getLongPrefix()
Returns the long prefix given at construction time.
|
ALcyProperties |
getProperties()
Returns the
ALcyProperties given at construction time. |
String |
getShortPrefix()
Returns the short prefix given at construction time.
|
boolean |
isApplicationPaneActive()
Returns
true if there is currently an ILcyApplicationPane active for this
ALcyApplicationPaneTool . |
void |
plugInto(ILcyLucyEnv aLucyEnv)
Plugs this tool.
|
void |
setApplicationPaneActive(boolean aApplicationPaneActive)
Programmatically sets the
ILcyApplicationPane to be active or not. |
void |
unplugFrom(ILcyLucyEnv aLucyEnv)
Unplugs this tool.
|
addPropertyChangeListener, addPropertyChangeListener, assertPlugged, firePropertyChange, getLongPrefix, getLongPrefixWithClassName, getLucyEnv, getShortPrefix, removePropertyChangeListener, removePropertyChangeListener
@Deprecated public ALcyApplicationPaneTool(ALcyProperties aProperties, Class aClass)
ALcyApplicationPaneTool(aProperties, getLongPrefix(aClass), getShortPrefix(aClass))
.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.ALcyApplicationPaneTool(com.luciad.lucy.util.properties.ALcyProperties, String, String)
,
ALcyTool.getLongPrefix(Class)
,
ALcyTool.getShortPrefix(Class)
public ALcyApplicationPaneTool(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix)
ALcyApplicationPaneTool
. The properties are retrieved from the
given properties.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.public ALcyProperties getProperties()
ALcyProperties
given at construction time.ALcyProperties
given at construction time.public String getLongPrefix()
public String getShortPrefix()
public ILcyApplicationPane getApplicationPane()
ILcyApplicationPane
if it is active, or null
when not active.
An "applicationPane"
PropertyChangeEvent
is fired if this property changes.null
, or the currently active ILcyApplicationPane
.public boolean isApplicationPaneActive()
true
if there is currently an ILcyApplicationPane
active for this
ALcyApplicationPaneTool
.
An "applicationPaneActive"
PropertyChangeEvent
is fired if this property changes.True
if the ILcyApplicationPane
is active, false
otherwise.setApplicationPaneActive(boolean)
public void setApplicationPaneActive(boolean aApplicationPaneActive)
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
.aApplicationPaneActive
- True
to activate the ILcyApplicationPane
,
false
to deactivate it.isApplicationPaneActive()
public void plugInto(ILcyLucyEnv aLucyEnv)
ALcyTool
Plugs this tool. This method is usually called from
ALcyAddOn#plugInto
.
public void unplugFrom(ILcyLucyEnv aLucyEnv)
ALcyTool
Unplugs this tool. This method is usually called from
ALcyAddOn#unplugFrom
.
unplugFrom
in class ALcyTool
aLucyEnv
- The environment to unplug from, must be identical to the environment given to
plugInto
.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.
ILcyApplicationPane
.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.
protected ILcyApplicationPane createApplicationPane()
ILcyApplicationPane
. Overwriting this method allows to create a
different ILcyApplicationPane
, or to fine tune the creation.ILcyApplicationPane
.public static final ALcyApplicationPaneTool create(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix, Supplier<? extends Component> aContentsSupplier)
ALcyApplicationPaneTool
instance where the contents of the
application pane is supplied by aContentsSupplier
.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.ILcdDisposable
, the dispose
method
will be called when the application pane is disposed.