Package com.luciad.lucy.gui

Class TLcyActionBarMediatorBuilder

java.lang.Object
com.luciad.lucy.gui.TLcyActionBarMediatorBuilder
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.

Debugging

To make debugging easier, you can turn on trace logging for the TLcyActionBarUtil and ALcyActionBar classes. Doing so wil result in the following:

  • Show blue borders around the action bars
  • Add a tooltip to the action bar showing debug information
  • Replace the tooltip of the items in the action bar to display the group descriptors
  • Right-clicking on an action bar item will show a pop-up menu containing info on how to insert an item in that specific action bar at that specific location.

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.

Since:
2016.0

  • Method Summary

    Modifier and Type
    Method
    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(TLcyActionBarManager aActionBarManager)
    Create a new TLcyActionBarMediatorBuilder instance
    static TLcyActionBarMediatorBuilder
    newInstance(ILcyLucyEnv aLucyEnv)
    Short for
    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.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • sourceActionBar

      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.

      Parameters:
      aSourceActionBar - The source action bar. After the mediate() method is called, only a WeakReference to this action bar will be kept.
      Returns:
      this instance

    • sourceActionBar

      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.

      Parameters:
      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
      Returns:
      this instance
      See Also:

    • sourceActionBarIncludingActiveContexts

      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:

      • Merging with the active contexts allows to show map-specific items in the menu bar, like the action to open data on the map.
      • The menu bar is directly available from the back-end (see 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.
      • Actions inserted into the source action bar (the one in the action bar manager) will be inserted in the target action bar.
      Parameters:
      aSourceActionBarName - The name by which the global source action bar is known in the TLcyActionBarManager
      Returns:
      this instance

    • targetActionBar

      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.

      Parameters:
      aTargetActionBar - The target action bar. After the mediate() method is called, only a WeakReference to this action bar will be kept.
      Returns:
      this instance

    • targetActionBar

      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.

      Parameters:
      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
      Returns:
      this instance

    • bidirectional

      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();
      Returns:
      this instance

    • 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.

    • newInstance

      public static TLcyActionBarMediatorBuilder newInstance(TLcyActionBarManager aActionBarManager)
      Create a new TLcyActionBarMediatorBuilder instance
      Parameters:
      aActionBarManager - The action bar manager, possibly null. When null, the methods which specify an action bar using an identifier cannot be used.
      Returns:
      a new TLcyActionBarMediatorBuilder instance

    • newInstance

      public static TLcyActionBarMediatorBuilder newInstance(ILcyLucyEnv aLucyEnv)
      Short for 
      
   TLcyActionBarMediatorBuilder
     .newInstance( aLucyEnv.getUserInterfaceManager().getActionBarManager() );
      Parameters:
      aLucyEnv - The Lucy back-end
      Returns:
      a new TLcyActionBarMediatorBuilder instance