Class ALcyApplicationPaneTool
- All Implemented Interfaces:
ILcdPropertyChangeSource
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.
Workspace support
When storing/restoring a workspace where the panel was visible, this tool will store/restore the application pane
itself, and delegate storing/restoring of the pane content to the workspace codec.
For this to work, you'll need to plug in an ALcyWorkspaceObjectCodec
for the content.
If there is no such codec, the tool will fall back to the createContent()
method to recreate the contents
when restoring the workspace.
You can also store 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 Summary
ConstructorsConstructorDescriptionALcyApplicationPaneTool
(ALcyProperties aProperties, Class aClass) Deprecated.Better use the constructor with explicit long and short prefix, to avoid any confusion.ALcyApplicationPaneTool
(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix) Creates a newALcyApplicationPaneTool
. -
Method Summary
Modifier and TypeMethodDescriptionprotected void
This method is called when disposing the application pane.static final ALcyApplicationPaneTool
create
(ALcyProperties aProperties, String aLongPrefix, String aShortPrefix, Supplier<? extends Component> aContentsSupplier) Utility method to create a newALcyApplicationPaneTool
instance where the contents of the application pane is supplied byaContentsSupplier
.protected ILcyApplicationPane
Factory method to create theILcyApplicationPane
.protected abstract Component
This method creates the content for theILcyApplicationPane
.Returns the currentILcyApplicationPane
if it is active, ornull
when not active.Returns the long prefix given at construction time.Returns theALcyProperties
given at construction time.Returns the short prefix given at construction time.boolean
Returnstrue
if there is currently anILcyApplicationPane
active for thisALcyApplicationPaneTool
.void
plugInto
(ILcyLucyEnv aLucyEnv) Plugs this tool.void
setApplicationPaneActive
(boolean aApplicationPaneActive) Programmatically sets theILcyApplicationPane
to be active or not.toString()
void
unplugFrom
(ILcyLucyEnv aLucyEnv) Unplugs this tool.Methods inherited from class com.luciad.lucy.util.ALcyTool
addPropertyChangeListener, addPropertyChangeListener, assertPlugged, firePropertyChange, getLongPrefix, getLongPrefixWithClassName, getLucyEnv, getShortPrefix, removePropertyChangeListener, removePropertyChangeListener
-
Constructor Details
-
ALcyApplicationPaneTool
Deprecated.Better use the constructor with explicit long and short prefix, to avoid any confusion. Functionally equivalent toALcyApplicationPaneTool(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 thisALcyApplicationPaneTool
, normally an extension ofALcyAddOn
. It is used to retrieve the long and short prefixes usinggetLongPrefix
andgetShortPrefix
. 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
Creates a newALcyApplicationPaneTool
. 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 ornull
. 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
-
toString
-
getProperties
Returns theALcyProperties
given at construction time.- Returns:
- the
ALcyProperties
given at construction time.
-
getLongPrefix
Returns the long prefix given at construction time.- Returns:
- the long prefix given at construction time.
-
getShortPrefix
Returns the short prefix given at construction time.- Returns:
- the short prefix given at construction time.
-
getApplicationPane
Returns the currentILcyApplicationPane
if it is active, ornull
when not active. An"applicationPane"
PropertyChangeEvent
is fired if this property changes.- Returns:
null
, or the currently activeILcyApplicationPane
.
-
isApplicationPaneActive
public boolean isApplicationPaneActive()Returnstrue
if there is currently anILcyApplicationPane
active for thisALcyApplicationPaneTool
. An"applicationPaneActive"
PropertyChangeEvent
is fired if this property changes.- Returns:
True
if theILcyApplicationPane
is active,false
otherwise.- See Also:
-
setApplicationPaneActive
public void setApplicationPaneActive(boolean aApplicationPaneActive) Programmatically sets theILcyApplicationPane
to be active or not. Activating theILcyApplicationPane
results ingetApplicationPane()
to return a value different fromnull
. De-activating theILcyApplicationPane
makesgetApplicationPane
returnnull
.- Parameters:
aApplicationPaneActive
-True
to activate theILcyApplicationPane
,false
to deactivate it.- See Also:
-
plugInto
Description copied from class:ALcyTool
Plugs this tool. This method is usually called from
ALcyAddOn#plugInto
. -
unplugFrom
Description copied from class:ALcyTool
Unplugs this tool. This method is usually called from
ALcyAddOn#unplugFrom
.- Overrides:
unplugFrom
in classALcyTool
- Parameters:
aLucyEnv
- The environment to unplug from, must be identical to the environment given toplugInto
.
-
createContent
This method creates the content for the
ILcyApplicationPane
. It is added to theILcyApplicationPane.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 callJComponent.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
Factory method to create theILcyApplicationPane
. Overwriting this method allows to create a differentILcyApplicationPane
, 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 newALcyApplicationPaneTool
instance where the contents of the application pane is supplied byaContentsSupplier
.- 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 ornull
. 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 thecreateContent()
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 implementsILcdDisposable
, thedispose
method will be called when the application pane is disposed.- Returns:
- An application pane tool
- Since:
- 2017.0
-