public class TLcyPreviewAddOn extends ALcyAddOn implements ILcdPropertyChangeSource
This add-on allows you to work with real-time data: it provides UI for playing back real-time data through time, and updates the data in the view accordingly.
The TLcyPreviewAddOn
is basically a wrapper around a TLcdSimulator
instance.
It provides similar methods, such as methods to set the current time
,
to control the time factor
, to start
and stop()
the
simulator, and so on.
The main difference with the TLcdSimulator
is that the TLcyPreviewAddOn
has built-in support for controlling multiple
real-time models at the same time.
The next section explains how you register real-time data with the TLcdSimulator
of the preview add-on.
Next to the API methods, the preview add-on also provides UI to the Lucy end user to control the time in the Lucy application. The preview UI can be customized through the API, as explained in one of the next sections.
There are 2 ways to register your real-time data with this add-on. Once your data is registered, both the API methods of this add-on and the UI controlled by the end user will work on your data.
ILcdMultiDimensionalModel
instances
This add-on automatically detects all the ILcdMultiDimensionalModel
instances with a TLcdDimensionAxis
of type Date
added to a view in Lucy.
Each time the date of the TLcdSimulator
changes, the multi-dimensional model will be
filtered
on its time
dimension.
This is the recommended way to add support for your own real-time data format in Lucy.
Note that no extra work is required if the ILcdModel
instances of your custom real-time data format
also implement ILcdMultiDimensionalModel
.
That mechanism is illustrated in the trajectory sample.
Internally, the preview add-on creates an ILcdSimulatorModel
instance for the ILcdMultiDimensionalModel
,
and registers that with the TLcdSimulator
(also known as the
adapter design pattern).
The ILcdSimulatorModel
is exposed in the various API methods of the preview add-on API.
For example, if you call getSimulatorModelCount()
, the count will include the ILcdSimulatorModel
instances representing the ILcdMultiDimensionalModel
s.
ILcdSimulatorModel
instances
You can create your own ILcdSimulatorModel
instances and register
(and de-register
) them with the TLcyPreviewAddOn
directly.
This mechanism allows you to decide when you make the simulator model available to the preview add-on and when you do not.
An example use case is a layer that wants to update itself (or its model) based on the current time while the ILcdModel
does not implement ILcdMultiDimensionalModel
.
To handle that case, add an ILcdSimulatorModel
to the preview add-on, and let that simulator model update the layer each time its
ILcdSimulatorModel.setDate(Date)
method is called.
You can modify the user interface by extending the TLcyPreviewAddOnCustomizerFactory
.
That factory is responsible for creating the UI, and exposes the creation process in several
small protected methods.
Override the method corresponding to the UI element you want to customize, and return a custom component.
This mechanism is very similar to the ALcyGUIFactory
mechanism.
You must either configure your custom TLcyPreviewAddOnCustomizerFactory
extension in the configuration
file
previewer.previewAddOnCustomizerFactoryName = mypackage.CustomPreviewAddOnCustomizerFactory
or set
it on this add-on using the API.
The user can open the UI through a menu item.
The location of this menu item is configurable in the configuration file of this add-on.
You can also use the setApplicationPaneActive(boolean)
method to open and close the UI through the API.
The map-centric version of Lucy uses that mechanism to place the custom time controls on the map
(see samples.lucy.frontend.mapcentric.previewer.PreviewerOnMapCustomizerFactory
).
All the methods of this class have to be called from the Event Dispatch Thread (EDT, also known as the Swing Thread or AWT thread).
The TLcyPreviewAddOn
also exposes methods to perform filtering (for example addSimulatorModelFilter(ILcdFilter)
)
and to register {@code PropertyChangeListener}s
.
Consult the method javadoc for more information.
ILcySimulatorModelFactory
API
Lucy has the concept of an ILcySimulatorModelFactory
: a factory that can create ILcdSimulatorModel
instances
for a static model.
The preview add-on will use all the simulator model factory instances
available on the Lucy back-end
to automatically create and register ILcdSimulatorModel
s
for all ILcdModel
instances added to a view.
If an ILcySimulatorModelFactory
is available for a model added to a view in Lucy, the preview add-on will
not only create a ILcdSimulatorModel
for that ILcdModel
.
It will also create layers for each of the track models
, and
add those layers to the view.
When the original static ILcdModel
is removed from the map, the preview add-on will remove the corresponding
track layers as well.
Note that, to properly integrate with workspaces, the code that registers the ILcySimulatorModelFactory
instance
on the back-end and the layer factory for the track models of the simulator model, must also register
ALcyWorkspaceObjectCodec
instances for the simulator models, the track models and the track layers.
The major drawback of this mechanism is that you need a model and layer representing the static data,
from which the real time model (the ILcdSimulatorModel
) can be derived.
Often such static data is not available.
A second drawback is that the static data must be present in the view, even if you do not need it.
Removing the static data removes the real-time data as well.
Due to these drawbacks, this mechanism has been deprecated in favor of the ILcdMultiDimensionalModel
mechanism.
Modifier and Type | Field and Description |
---|---|
static TLcyGroupDescriptor |
PREVIEW_GROUP_DESCRIPTOR
Group descriptor which can be used when inserting preview actions in an action bar.
|
Constructor and Description |
---|
TLcyPreviewAddOn()
Creates a new
TLcyPreviewAddOn . |
Modifier and Type | Method and Description |
---|---|
void |
addPreviewAddOnListener(ILcyPreviewAddOnListener aListener)
Adds a preview add-on listener to this add-on.
|
void |
addPropertyChangeListener(PropertyChangeListener aListener)
Registers the given
PropertyChangeListener to be notified when this object's
properties change. |
void |
addSimulatorModel(ILcdSimulatorModel aSimulatorModel)
Deprecated.
Use the
addSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel) instead of
this method, and manage the creation and addition of the layers manually. |
void |
addSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
Adds a simulator model filter.
|
void |
addSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
Adds a
ILcdSimulatorModel and notifies all ILcyPreviewAddOnListener 's of the change. |
protected void |
firePreviewAddOnEvent(TLcyPreviewAddOnEvent aEvent)
Notifies all registered
ILcyPreviewAddOnListener s about the given event. |
protected void |
firePropertyChange(PropertyChangeEvent aEvent)
Fires the given property change event to the associated listeners.
|
Date |
getBeginDate()
Returns the begin date.
|
Date |
getDate()
Returns the current date of the previewer.
|
DateFormat |
getDateFormat()
Deprecated.
Do not use this method.
Lucy has now an application-wide format to control how dates are presented to the user.
Use
ILcyLucyEnv.getDefaultDateTimeFormat() instead. |
int |
getDelayBetweenUpdateMs()
Returns the delay between updates in milliseconds.
|
Date |
getEndDate()
Returns the end date.
|
Date |
getFilterBeginDate()
Returns the begin date of the filter.
|
Date |
getFilterEndDate()
Returns the end date of the filter.
|
int |
getMaxCPUUsage()
Returns the maximum cpu usage of the previewer.
|
ALcyPreviewAddOnCustomizerFactory |
getPreviewAddOnCustomizerFactory()
Returns the
TLcyPreviewAddOnCustomizerFactory that is responsible to create the gui panel. |
ILcdSimulatorModel |
getSimulatorModel(int aIndex)
Returns the simulator model at the given index.
|
int |
getSimulatorModelCount()
Returns the number of simulator models.
|
String |
getSimulatorModelDisplayName(ILcdSimulatorModel aSimulatorModel)
Returns the display name for a simulator model.
|
ILcdFilter<ILcdSimulatorModel> |
getSimulatorModelFilter(int aIndex)
Returns the simulator model filter at the given index.
|
int |
getSimulatorModelFilterCount()
Returns the number of simulator model filters that have been added.
|
int |
getStatus()
Returns the status of the previewer.
|
String |
getStatusAsString()
Returns the status, formatted as a string.
|
double |
getTimeFactor()
Returns the time factor used by the previewer.
|
long |
getTimeStep()
Returns the time step in milliseconds.
|
int |
getUpdatesPerSecond()
Returns the current update rate in updates per second.
|
boolean |
isApplicationPaneActive()
Returns
true if the ILcyApplicationPane is currently active, false
otherwise. |
boolean |
isPauseOnMousePressed()
Returns whether the simulation is paused while the mouse is pressed.
|
boolean |
isTraceOn()
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
boolean |
isUseTimeStep()
Returns
true if using time steps, false otherwise. |
void |
pause()
Pauses the previewer.
|
void |
plugInto(ILcyLucyEnv aLucyEnv)
Plugs this addon into the given lucy environment.
|
void |
removePreviewAddOnListener(ILcyPreviewAddOnListener aListener)
Removes the given preview add-on listener from this add-on.
|
void |
removePropertyChangeListener(PropertyChangeListener aListener)
De-registers the given
PropertyChangeListener from receiving property change events
for this object. |
void |
removeSimulatorModel(ILcdSimulatorModel aSimulatorModel)
Deprecated.
Use the
removeSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel)
instead of this method, and manage the creation and addition of the layers
manually |
void |
removeSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
Removes the given filter.
|
void |
removeSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
Removes a
ILcdSimulatorModel
and notifies all the
ILcyPreviewAddOnListener 's
of the change. |
void |
run()
Runs the previewer.
|
void |
setApplicationPaneActive(boolean aActive)
Sets the active state of the preview
ILcyApplicationPane . |
static void |
setClassTraceOn(boolean aClassTraceOn)
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
setDate(Date aDate)
Sets the current date of the previewer.
|
void |
setDateFormat(DateFormat aDateFormat)
Deprecated.
Do not use this method.
Lucy has now an application-wide format to control how dates are presented to the user.
Use
ILcyLucyEnv.setDefaultDateTimeFormat(java.text.Format) instead. |
void |
setDelayBetweenUpdateMs(int aDelayBetweenUpdateMs)
Set the minimal delay in milliseconds between two simulation updates.
|
void |
setFilterBeginDate(Date aDate)
Sets the begin date of the filter.
|
void |
setFilterEndDate(Date aDate)
Sets the end date of the filter.
|
void |
setMaxCPUUsage(int aMaxCPUUsage)
Sets the maximum cpu usage.
|
void |
setPauseOnMousePressed(boolean aPause)
Set whether to pause the simulation when the mouse is pressed on one of the simulation views.
|
void |
setPreviewAddOnCustomizerFactory(ALcyPreviewAddOnCustomizerFactory aPreviewAddOnCustomizerFactory)
Sets the
TLcyPreviewAddOnCustomizerFactory that is responsible to create the gui panel. |
void |
setTimeFactor(double aTimeFactor)
Sets the time factor, i.e. the factor by which simulation is accelerated with respect to real time.
|
void |
setTimeStep(long aTimeStep)
Sets the time step to use expressed in milliseconds.
|
void |
setTraceOn(boolean aTraceOn)
Deprecated.
This method has been deprecated. It is recommended to use the
standard Java logging framework directly.
|
void |
setUseTimeStep(boolean aUseTimeStep)
Sets whether to use a time-step simulation.
|
void |
stop()
Stops the previewer.
|
void |
unplugFrom(ILcyLucyEnv aLucyEnv)
Unplugs this addon from the given Lucy environment.
|
getConfigSourceName, getDisplayName, setConfigSourceName, setDisplayName
public static final TLcyGroupDescriptor PREVIEW_GROUP_DESCRIPTOR
@Deprecated public static void setClassTraceOn(boolean aClassTraceOn)
true
then all log messages are recorded, otherwise only
the informative, warning and error messages are recorded.aClassTraceOn
- if true then all log messages are recorded,
otherwise only the informative, warning and error messages are recorded.@Deprecated public void setTraceOn(boolean aTraceOn)
true
or false
as argument automatically turns
off tracing for all other class instances for which
setTraceOn
has not been called.
If the argument is false
then only the informative, warning
and error log messages are recorded.aTraceOn
- if true then all log messages are recorded for this
instance. If false, then only the informative, warning and
error log messages are recorded.@Deprecated public boolean isTraceOn()
true
if tracing is enabled for this class.public void plugInto(ILcyLucyEnv aLucyEnv)
ALcyAddOn
plugInto
in class ALcyAddOn
aLucyEnv
- The lucy environment to plug into.ALcyAddOn.unplugFrom(com.luciad.lucy.ILcyLucyEnv)
public void unplugFrom(ILcyLucyEnv aLucyEnv)
ALcyAddOn
unplugFrom
in class ALcyAddOn
aLucyEnv
- The lucy environment to unplug from.ALcyAddOn.plugInto(com.luciad.lucy.ILcyLucyEnv)
public boolean isApplicationPaneActive()
true
if the ILcyApplicationPane
is currently active, false
otherwise.true
if the ILcyApplicationPane
is currently active, false
otherwise.setApplicationPaneActive(boolean)
public void setApplicationPaneActive(boolean aActive)
ILcyApplicationPane
. Active means the
ILcyApplicationPane
is present in the user interface.
Note that loading a workspace can change this property.aActive
- True
to make sure the ILcyApplicationPane
is present in the user
interface, false
to make sure the ILcyApplicationPane
is not present.public ALcyPreviewAddOnCustomizerFactory getPreviewAddOnCustomizerFactory()
TLcyPreviewAddOnCustomizerFactory
that is responsible to create the gui panel.TLcyPreviewAddOnCustomizerFactory
that is responsible to create the gui panel.setPreviewAddOnCustomizerFactory(com.luciad.lucy.addons.previewer.view.ALcyPreviewAddOnCustomizerFactory)
public void setPreviewAddOnCustomizerFactory(ALcyPreviewAddOnCustomizerFactory aPreviewAddOnCustomizerFactory)
TLcyPreviewAddOnCustomizerFactory
that is responsible to create the gui panel.aPreviewAddOnCustomizerFactory
- The factory.getPreviewAddOnCustomizerFactory()
public void addPropertyChangeListener(PropertyChangeListener aListener)
ILcdPropertyChangeSource
Registers the given PropertyChangeListener
to be notified when this object's
properties change.
In case you need to register a listener which keeps a reference to an object with a shorter life-time than this change source,
you can use a ALcdWeakPropertyChangeListener
instance as property change listener.
addPropertyChangeListener
in interface ILcdPropertyChangeSource
aListener
- The listener to be notifiedALcdWeakPropertyChangeListener
,
ILcdPropertyChangeSource.removePropertyChangeListener(java.beans.PropertyChangeListener)
public void removePropertyChangeListener(PropertyChangeListener aListener)
ILcdPropertyChangeSource
De-registers the given PropertyChangeListener
from receiving property change events
for this object.
If the listener was added more than once, it will be notified one less time after being
removed.
If the listener is null
, or was never added, no exception is thrown and no action is taken.
removePropertyChangeListener
in interface ILcdPropertyChangeSource
aListener
- the listener that should no longer be notified of changes of
this object's propertiesILcdPropertyChangeSource.addPropertyChangeListener(java.beans.PropertyChangeListener)
protected void firePropertyChange(PropertyChangeEvent aEvent)
aEvent
- The event to fire.addPropertyChangeListener(java.beans.PropertyChangeListener)
public void addPreviewAddOnListener(ILcyPreviewAddOnListener aListener)
aListener
- The listener to add.removePreviewAddOnListener(com.luciad.lucy.addons.previewer.ILcyPreviewAddOnListener)
public void removePreviewAddOnListener(ILcyPreviewAddOnListener aListener)
aListener
- The listener to remove.addPreviewAddOnListener(com.luciad.lucy.addons.previewer.ILcyPreviewAddOnListener)
protected void firePreviewAddOnEvent(TLcyPreviewAddOnEvent aEvent)
ILcyPreviewAddOnListener
s about the given event.aEvent
- The event to fire.@Deprecated public DateFormat getDateFormat()
ILcyLucyEnv.getDefaultDateTimeFormat()
instead.setDateFormat(java.text.DateFormat)
@Deprecated public void setDateFormat(DateFormat aDateFormat)
ILcyLucyEnv.setDefaultDateTimeFormat(java.text.Format)
instead.aDateFormat
- The date format to set.getDateFormat()
@Deprecated public void addSimulatorModel(ILcdSimulatorModel aSimulatorModel)
addSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel)
instead of
this method, and manage the creation and addition of the layers manually.ILcdSimulatorModel
and notifies all the
ILcyPreviewAddOnListener
's of
the change. Layers will be created for the track models of the simulator model and added to the
first GXY view (the GXY view of the map component at index 0 in the map manager)aSimulatorModel
- The ILcdSimulatorModel
to
add.@Deprecated public void removeSimulatorModel(ILcdSimulatorModel aSimulatorModel)
removeSimulatorModelNoLayers(com.luciad.realtime.ILcdSimulatorModel)
instead of this method, and manage the creation and addition of the layers
manuallyILcdSimulatorModel
and notifies all
the ILcyPreviewAddOnListener
's of the change.aSimulatorModel
- The simulator model to remove.public void addSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
ILcdSimulatorModel
and notifies all ILcyPreviewAddOnListener
's of the change. Note that the ILcdSimulatorModel
can provide
track models, but no layers are created for those, nor added to the map. You have full control
instead. Refer to the class comment for a more detailed explanation.aSimulatorModel
- The ILcdSimulatorModel
to
add.public void removeSimulatorModelNoLayers(ILcdSimulatorModel aSimulatorModel)
ILcdSimulatorModel
and notifies all the
ILcyPreviewAddOnListener
's
of the change.aSimulatorModel
- The simulator model to remove.public ILcdSimulatorModel getSimulatorModel(int aIndex)
aIndex
- The index to retrieve the simulator model for. 0 <= aIndex < getSimulatorModelCount()getSimulatorModelCount()
public int getSimulatorModelCount()
public void addSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
aFilter
- The filter to add.removeSimulatorModelFilter(com.luciad.util.ILcdFilter<com.luciad.realtime.ILcdSimulatorModel>)
public void removeSimulatorModelFilter(ILcdFilter<ILcdSimulatorModel> aFilter)
aFilter
- The filter to remove.addSimulatorModelFilter(com.luciad.util.ILcdFilter<com.luciad.realtime.ILcdSimulatorModel>)
public int getSimulatorModelFilterCount()
public ILcdFilter<ILcdSimulatorModel> getSimulatorModelFilter(int aIndex)
aIndex
- The index to retrieve the filter for. 0 <= aIndex < getSimulatorModelFilterCount()getSimulatorModelFilterCount()
public Date getDate()
setDate(java.util.Date)
public void setDate(Date aDate)
aDate
- The data.getDate()
,
TLcdSimulator.setDate(java.util.Date)
public int getMaxCPUUsage()
setMaxCPUUsage(int)
public void setMaxCPUUsage(int aMaxCPUUsage)
aMaxCPUUsage
- The maximum cpu usage.getMaxCPUUsage()
,
TLcdSimulator.setMaxCPUUsage(int)
public int getStatus()
TLcdSimulator.getStatus()
public String getStatusAsString()
TLcdSimulator.getStatusAsString()
public double getTimeFactor()
setTimeFactor(double)
public void setTimeFactor(double aTimeFactor)
aTimeFactor
- The time factor.getTimeFactor()
,
TLcdSimulator.setTimeFactor(double)
public long getTimeStep()
setTimeStep(long)
public void setTimeStep(long aTimeStep)
UseTimeStep
and TimeStep
, the standard user interface
should be adapted because the TimeFactor
property will be ignored.aTimeStep
- The time step.getTimeStep()
,
TLcdSimulator.setTimeStep(long)
public boolean isUseTimeStep()
true
if using time steps, false
otherwise.true
if using time steps, false
otherwise.setUseTimeStep(boolean)
,
getTimeStep()
public void setUseTimeStep(boolean aUseTimeStep)
true
, (and if the method getTimeStep())
returns a value > 0), the simulator will not perform a simulation that has a relation with the real
elapsed time. Instead it will give an animation at successive time step as fast as it can. By default,
this feature is disabledaUseTimeStep
- The value to be set for time-stepping.isUseTimeStep()
,
setTimeStep(long)
,
TLcdSimulator.setUseTimeStep(boolean)
public boolean isPauseOnMousePressed()
setPauseOnMousePressed(boolean)
public void setPauseOnMousePressed(boolean aPause)
aPause
- When true
, the simulation will pause while the mouse is being pressed.isPauseOnMousePressed()
,
TLcdSimulator.setPauseOnMousePressed(boolean)
public int getUpdatesPerSecond()
getStatus()
== TLcdSimulator.RUNNING
.TLcdSimulator.getUpdatesPerSecond()
public int getDelayBetweenUpdateMs()
setDelayBetweenUpdateMs(int)
public void setDelayBetweenUpdateMs(int aDelayBetweenUpdateMs)
aDelayBetweenUpdateMs
- The delay in milliseconds between two simulation updates.getDelayBetweenUpdateMs()
,
TLcdSimulator.setDelayBetweenUpdateMs(int)
public Date getBeginDate()
public Date getEndDate()
public Date getFilterBeginDate()
setFilterBeginDate(java.util.Date)
public void setFilterBeginDate(Date aDate)
aDate
- The begin date.getFilterBeginDate()
public Date getFilterEndDate()
setFilterEndDate(java.util.Date)
public void setFilterEndDate(Date aDate)
aDate
- The end date.getFilterEndDate()
public void run()
public void pause()
public void stop()
public String getSimulatorModelDisplayName(ILcdSimulatorModel aSimulatorModel)
aSimulatorModel
- The simulator model to retrieve the display name for.