public final class TLcyActionBarMediatorBuilder extends Object
Builder class which allows to mediate the actions and active settables between two action bars. It allows to keep two action bars in sync: all current and future actions and active settables of one action bar can automatically be added to the other action bar.
For example if you add an action bar to a map component, you might want to keep the contents of the
action bar in the UI in sync with the contents of the action bar in the TLcyActionBarManager
.
This can be done using the following code:
ILcyActionBar actionBarForUI = ...;
ILspMapComponent map = ...;
TLcyActionBarMediatorBuilder.newInstance( lucy )
.sourceActionBar( "actionBarID", map )
.targetActionBar(actionBarForUI)
.bidirectional()
.mediate();
The Lucy developer guide has a chapter dedicated to working with action bars (chapter "Modifying the menu and tool bars"). This chapter contains more information about the action bar manager, and mediating action bars.
To make debugging easier, you can turn on trace logging for the TLcyActionBarUtil
and ALcyActionBar
classes.
Doing so wil result in the following:
Trace logging for those classes can be enabled by adding the following lines to your logging properties file:
com.luciad.lucy.gui.TLcyActionBarUtil.level = FINEST
com.luciad.lucy.gui.ALcyActionBar.level = FINEST
Note: the TLcyDebugAddOn
adds UI items to Lucy to activate
the debugging hints for the action bars.
The TLcyActionBarManager.generateDump()
method can also be useful when investigating why certain actions
do or do not appear in an action bar.
Modifier and Type | Method and Description |
---|---|
TLcyActionBarMediatorBuilder |
bidirectional()
Calling this method will trigger synchronization in both directions: actions and active settables added to
the source action bar will automatically be added to the target action bar, and actions and active settables added to
target action bar will automatically be added to the source action bar.
|
void |
mediate()
Starts the actual mediation between the two action bars with the specified settings of this object.
|
static TLcyActionBarMediatorBuilder |
newInstance(ILcyLucyEnv aLucyEnv)
Short for
|
static TLcyActionBarMediatorBuilder |
newInstance(TLcyActionBarManager aActionBarManager)
Create a new
TLcyActionBarMediatorBuilder instance |
TLcyActionBarMediatorBuilder |
sourceActionBar(ILcyActionBar aSourceActionBar)
Sets the source action bar: all (current and future) actions and active settables from this action bar will
be added to the target action bar.
In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager ,
and the target action bar is the action bar which is shown in the UI. |
TLcyActionBarMediatorBuilder |
sourceActionBar(String aSourceActionBarName,
Object aSourceActionBarContext)
Sets the source action bar by specifying the name and context by which it is known in the
TLcyActionBarManager :
all (current and future) actions and active settables from this action bar will be added to the target action bar.In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager ,
and the target action bar is the action bar which is shown in the UI. |
TLcyActionBarMediatorBuilder |
sourceActionBarIncludingActiveContexts(String aSourceActionBarName)
Sets the global source action bar by specifying the name by which it is known in the
TLcyActionBarManager :
all (current and future) actions and active settables from this global action bar will be added to the target action bar,
as well as all (current and future) actions and active settables of the non-global action bar
of all the active contexts . |
TLcyActionBarMediatorBuilder |
targetActionBar(ILcyActionBar aTargetActionBar)
Sets the target action bar: all (current and future) actions and active settables of the
source action bar
will be added to this action bar.In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager ,
and the target action bar is the action bar which is shown in the UI. |
TLcyActionBarMediatorBuilder |
targetActionBar(String aTargetActionBarName,
Object aTargetActionBarContext)
Sets the target action bar by specifying the name and context by which it is known in the
TLcyActionBarManager :
all (current and future) actions and active settables of the source action bar
will be added to this action bar.In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager ,
and the target action bar is the action bar which is shown in the UI. |
public TLcyActionBarMediatorBuilder sourceActionBar(ILcyActionBar aSourceActionBar)
Sets the source action bar: all (current and future) actions and active settables from this action bar will
be added to the target action bar.
In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager
,
and the target action bar is the action bar which is shown in the UI.
Using this method will not show all the debug information when activating trace logging (see class javadoc).
Use sourceActionBar(String, Object)
instead when the source action bar is present in the TLcyActionBarManager
.
aSourceActionBar
- The source action bar.
After the mediate()
method is called, only a WeakReference
to this action bar
will be kept.public TLcyActionBarMediatorBuilder sourceActionBar(String aSourceActionBarName, Object aSourceActionBarContext)
Sets the source action bar by specifying the name and context by which it is known in the TLcyActionBarManager
:
all (current and future) actions and active settables from this action bar will be added to the target action bar.
In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager
,
and the target action bar is the action bar which is shown in the UI.
aSourceActionBarName
- The name by which the action bar is known in the TLcyActionBarManager
aSourceActionBarContext
- The context by which the action bar is known in the TLcyActionBarManager
TLcyActionBarManager.getActionBar(String, Object)
public TLcyActionBarMediatorBuilder sourceActionBarIncludingActiveContexts(String aSourceActionBarName)
Sets the global source action bar by specifying the name by which it is known in the TLcyActionBarManager
:
all (current and future) actions and active settables from this global action bar will be added to the target action bar,
as well as all (current and future) actions and active settables of the non-global action bar
of all the active contexts
.
This is best explained by using an example:
If for example your application has a menu bar which is always visible, independent of the currently active contexts, you might want to add "global actions" (e.g. an action to exit the application), and actions specific to the currently active contexts like the map (e.g. an action to open data on the map):
ILcyActionBar menuBarForUI = ...;
TLcyActionBarMediatorBuilder.newInstance( lucy )
.sourceActionBarIncludingActiveContexts( "menuBar" )
.targetActionBar(menuBarForUI)
.mediate();
The result of the above call will be that all current and future actions and active settables from the
action bar with name "menuBar" and context null
are added to the target action bar.
When a context becomes active (like when creating a map), all current and future actions and active settables
of the action bar with name "menuBar" and that context will be added to the target action bar
as well.
In this example, this means that all actions and active settables which are configured to appear in the menuBar
of the map will be added to the target action bar.
The moment the context is no longer active (e.g. the map is closed, or another map gains focus), those actions and active settables are removed again from the target action bar.
A common use-case for this method is to use it in combination with the bidirectional()
method.
This is for example done for the standard menu bar in Lucy, and offers the following functionality:
ILcyLucyEnv.getMainMenuBar()
).
Thanks to the bidirectional()
call, any actions inserted directly in the menu bar
will be inserted in the source action bar as well.
This means that those actions can be retrieved from the action bar manager by other add-ons.
aSourceActionBarName
- The name by which the global source action bar is known in the TLcyActionBarManager
public TLcyActionBarMediatorBuilder targetActionBar(ILcyActionBar aTargetActionBar)
Sets the target action bar: all (current and future) actions and active settables of the source action bar
will be added to this action bar.
In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager
,
and the target action bar is the action bar which is shown in the UI.
aTargetActionBar
- The target action bar.
After the mediate()
method is called, only a WeakReference
to this action bar
will be kept.public TLcyActionBarMediatorBuilder targetActionBar(String aTargetActionBarName, Object aTargetActionBarContext)
Sets the target action bar by specifying the name and context by which it is known in the TLcyActionBarManager
:
all (current and future) actions and active settables of the source action bar
will be added to this action bar.
In the most typical scenario, the source action bar is the action bar registered in the TLcyActionBarManager
,
and the target action bar is the action bar which is shown in the UI.
aTargetActionBarName
- The name by which the action bar is known in the TLcyActionBarManager
aTargetActionBarContext
- The context by which the action bar is known in the TLcyActionBarManager
public TLcyActionBarMediatorBuilder bidirectional()
Calling this method will trigger synchronization in both directions: actions and active settables added to the source action bar will automatically be added to the target action bar, and actions and active settables added to target action bar will automatically be added to the source action bar.
Note that if bidirectional synchronization is required, you must call this method. It is not allowed to call this mediator twice, e.g. the following code is invalid:
ILcyActionBar source = ...;
ILcyActionBar target = ...;
//The following construct is invalid, use the bidirectional() method instead
TLcyActionBarMediatorBuilder.newInstance( lucy ).sourceActionBar( source ).targetActionBar( target ).mediate();
TLcyActionBarMediatorBuilder.newInstance( lucy ).sourceActionBar( target ).targetActionBar( source ).mediate();
public void mediate()
Starts the actual mediation between the two action bars with the specified settings of this object.
After calling this method, no further interaction with this object is allowed. Every subsequent method call will throw exceptions.
public static TLcyActionBarMediatorBuilder newInstance(TLcyActionBarManager aActionBarManager)
TLcyActionBarMediatorBuilder
instanceaActionBarManager
- The action bar manager, possibly null
.
When null
, the methods which specify an action bar using an identifier cannot be used.TLcyActionBarMediatorBuilder
instancepublic static TLcyActionBarMediatorBuilder newInstance(ILcyLucyEnv aLucyEnv)
TLcyActionBarMediatorBuilder
.newInstance( aLucyEnv.getUserInterfaceManager().getActionBarManager() );
aLucyEnv
- The Lucy back-endTLcyActionBarMediatorBuilder
instance