Package com.luciad.lucy.gui

Class TLcyActionBarUtil

java.lang.Object
com.luciad.lucy.gui.TLcyActionBarUtil
public class TLcyActionBarUtil extends Object

A class containing static utility methods to facilitate working with action bars. When you encounter a problem related to actions or active settables and action bars like for example action which do not appear, appear in the wrong location, appear in the wrong order, ... the TLcyDebugAddOn can be of great help.

The most important methods of this class are illustrated in the Lucy developer guide in the "Modifying the menu and tool bars" chapter. This chapter contains code examples for all common operations with action bars.

The most important functions of this class are:

  • Using configuration options to insert an action / active settable in action bars: the insertInConfiguredActionBars methods allow you to pass in an action or active settable and the configuration file, and the item will automatically be inserted in all action bars which are present in the configuration file.
  • Setting up your own action bar: the setupAsConfiguredActionBar method allows you to create your own action bar in which actions can be inserted using the insertInConfiguredActionBars methods. This also allows to configure existing actions to appear in it.

Note: when you run into problems with action bars, you could try the debugging options outlined in the class javadoc of TLcyActionBarMediatorBuilder.

Since:
8.1
See Also:

  • Field Details

  • Method Details

    • setupAsConfiguredActionBar

      public static ILcdDisposable setupAsConfiguredActionBar(ILcyActionBar aActionBarSFCT, String aActionBarID, Object aContext, ALcyProperties aProperties, String aPropertiesPrefix, JComponent aTargetAcceleratorKeysComponent, TLcyActionBarManager aActionBarManager)

      Utility method to setup an ILcyActionBar as 'configured action bar' designed to contain actions and active settables for the specified context.

      You typically call this method when you created your own action bar to insert into the UI, and you want it to behave like the standard Lucy action bars. Consult the "Modifying the menu and tool bars" chapter in the Lucy developer guide for more information.

      This method will ensure that:

      • Actions and active settables registered at the action bar manager appear in aActionBarSFCT.
        When the specified context is not null, the action bar will also contain all global actions and active settables registered for aActionBarID. The major benefit is that this allows you to configure global actions (e.g. File | New | Map ) into a map specific action bar like the map tool bar.
      • The sorting of the different groups specified as specified in the configuration files is respected. This requires that aActionBarSFCT is an ALcyActionBar instance.
      • The accelerator keys of all existing and future actions and active settables are added to the action map of aTargetAcceleratorKeysComponent. Triggering the accelerator key of such action or active settable on aTargetAcceleratorKeysComponent will trigger the corresponding action or active settable.
        Suppose there is a UI panel with some functionality, and it contains a tool bar. If a short cut key is used while the focus is in one of the sub-components of the panel, you probably want it to trigger the respective tool bar action. This is ensured by calling this method.
      Parameters:
      aActionBarSFCT - The action bar. Must not be null. The sorting defined in aProperties will only be respected when this is a ALcyActionBar instance.
      aActionBarID - The ID for the action bar
      aContext - The context for the action bar. Typically null or an ILcyGenericMapComponent
      aProperties - The properties instance containing the settings of the action bar. Consult the javadoc of ALcyActionBar.setProperties(ALcyProperties) for more information.
      aPropertiesPrefix - The prefix used in aProperties
      aTargetAcceleratorKeysComponent - The component that should respond to pressing accelerator keys (a.k.a. hot keys) that are configured in the action bar. This is typically the panel to which the action bar 'belongs'. For example, the map tool bar would provide the map here. May be null.
      aActionBarManager - The action bar manager
      Returns:
      an ILcdDisposable, allowing to clean up all bindings between aActionBarSFCT and aTargetAcceleratorKeysComponent. In most cases you can ignore the return value. You only need to call dispose on the ILcdDisposable when the lifetime of aActionBarSFCT is different from the lifetime of aTargetAcceleratorKeysComponent. In that case, you need to dispose the disposable when one of both instances is end-of-life.

    • mediateAcceleratorKeys

      public static ILcdDisposable mediateAcceleratorKeys(ILcyActionBar aActionBar, JComponent aTargetComponent)

      Mediates the accelerator keys between the ILcyActionBar and the JComponent. All existing and future ILcdAction and ILcyActiveSettable accelerator keys will be added in the action map of the JComponent, and triggering the accelerator key on the JComponent will trigger the corresponding ILcdAction or ILcyActiveSettable.

      Suppose there is a UI panel with some functionality, and it contains a tool bar. If a short cut key is used while the focus is in one of the sub-components of the panel, you probably want it to trigger the respective tool bar action. For this to work, this method needs to be called.

      Parameters:
      aActionBar - The action bar. Must not be null
      aTargetComponent - The target component. Must not be null
      Returns:
      an ILcdDisposable, allowing to stop mediating the two instances. Calling the ILcdDisposable.dispose() method will clean up all bindings between aActionBar and aTargetComponent, and will remove all accelerator keys of aActionBar from aTargetComponent. Typically the life time of aActionBar and aTargetComponent is the same. In such case, there is no need to call the dispose method.

    • mediate

      @Deprecated public static void mediate(ILcyActionBar aFirst, ILcyActionBar aSecond)
      Deprecated.
      The recommended way to mediate between two action bars is to use the TLcyActionBarMediatorBuilder class

      Mediates between the two given action bars. Short for: 

      
  TLcyActionBarMediatorBuilder.newInstance(aActionBarManager)
    .sourceActionBar(aFirst)
    .targetActionBar(aSecond)
    .bidirectional()
    .mediate();

      Consult the documentation of TLcyActionBarMediatorBuilder for more information.

      Parameters:
      aFirst - The first action bar. Note that this method will only keep a WeakReference to this action bar.
      aSecond - The second action bar. Note that this method will only keep a WeakReference to this action bar.

    • mediate

      @Deprecated public static void mediate(ILcyActionBar aSource, ILcyActionBar aTarget, boolean aBidirectional)
      Deprecated.
      The recommended way to mediate between two action bars is to use the TLcyActionBarMediatorBuilder class

      Mediates between the two given action bars. Short for: 

      
  TLcyActionBarMediatorBuilder mediator = TLcyActionBarMediatorBuilder.newInstance( aActionBarManager )
                                                .sourceActionBar(aSource)
                                                .targetActionBar(aTarget);
  if ( aBidirectional ){
    mediator.bidirectional();
  }
  mediator.mediate();

      Consult the documentation of TLcyActionBarMediatorBuilder for more information.

      Note that if bidirectional synchronization is required, it is not valid to call this method twice with aBidirectional set to false, e.g. 

      
   mediate( aBar, aOtherBar, false );
   mediate( aOtherBar, aBar, false );
      Parameters:
      aSource - The action bar with which the other action bar should be mediated. It should not be null. Note that this method will only keep a WeakReference to this action bar.
      aTarget - The action bar with which aSource should be mediated. It must not be null. Note that this method will only keep a WeakReference to this action bar.
      aBidirectional - true if synchronization between the two actions bars should happen in both directions, false to only synchronize from source to target.

    • mediate

      @Deprecated public static void mediate(ILcyActionBar aTargetActionBar, String aActionBarID, boolean aMerge, TLcyActionBarManager aActionBarManager)
      Deprecated.
      The recommended way to mediate between two action bars is to use the TLcyActionBarMediatorBuilder class

      Mediates between the two given action bars. Short for: 

      
  if ( aMerge ) {
    TLcyActionBarMediatorBuilder.newInstance(aActionBarManager)
                     .sourceActionBarIncludingActiveContexts(aActionBarID)
                     .targetActionBar(aTargetActionBar)
                     .bidirectional()
                     .mediate();
  } else {
  TLcyActionBarMediatorBuilder.newInstance(aActionBarManager)
                   .sourceActionBar(aActionBarID, null)
                   .targetActionBar(aTargetActionBar)
                   .bidirectional()
                   .mediate();
  }

      Consult the documentation of TLcyActionBarMediatorBuilder for more information.

      Parameters:
      aTargetActionBar - The ILcyActionBar to which the actions of the global action bar, and possibly the actions of the action bars of the active contexts, should be added. Note that this method will only keep a WeakReference to this action bar.
      aActionBarID - The ID of the action bar in the action manager.
      aMerge - If true, the actions of the action bars of the active contexts will also be added to the given aTargetActionBar. If false, this method acts exactly as mediate(aTargetActionBar, aActionBarID, null,aActionBarManager)
      aActionBarManager - The action bar manager containing the requested action bars.
      See Also:

    • mediate

      @Deprecated public static void mediate(ILcyActionBar aTargetActionBar, String aActionBarID, Object aContext, TLcyActionBarManager aActionBarManager)
      Deprecated.
      The recommended way to mediate between two action bars is to use the TLcyActionBarMediatorBuilder class

      Mediates between the two given action bars. Short for: 

      
  TLcyActionBarMediatorBuilder.newInstance(aActionBarManager)
                   .sourceActionBar(aActionBarID, aContext)
                   .targetActionBar(aTargetActionBar)
                   .bidirectional()
                   .mediate();

      Consult the documentation of TLcyActionBarMediatorBuilder for more information.

      Parameters:
      aTargetActionBar - The action bar with which the other action bar should be mediated. It should not be null. Note that this method will only keep a WeakReference to this action bar.
      aActionBarID - The ID of the action bar in the TLcyActionBarManager.
      aContext - The context of the action bar in the TLcyActionBarManager.
      aActionBarManager - The action bar manager.
      See Also:

    • findAction

      public static ILcdAction findAction(String aActionID, String aActionBarID, Object aActionBarContext, TLcyActionBarManager aActionBarManager)

      Returns the action with id aActionID from the action bar identified by aActionBarID and aActionBarContext.

      Short for: 
      
   TLcyActionBarUtil.findAction(aActionID, aActionBarManager.getActionBar(aActionBarID, aActionBarContext))
      Parameters:
      aActionID - The id of the action
      aActionBarID - The id of the action bar
      aActionBarContext - The context of the action bar
      aActionBarManager - The action bar manager
      Returns:
      the action with the specified id from the action bar, or null when not found
      Since:
      2014.0
      See Also:

    • findAction

      public static ILcdAction findAction(String aActionID, ILcyActionBar aActionBar)

      Method which loops over all actions present in aActionBar, and returns the action with value aActionID for the key ID_KEY.

      Parameters:
      aActionID - The id of the searched action
      aActionBar - The action bar to search
      Returns:
      The action with the specified id, or null when no such action exists in aActionBar.
      Since:
      2014.0
      See Also:

    • findActiveSettable

      public static ILcyActiveSettable findActiveSettable(String aActiveSettableID, String aActionBarID, Object aActionBarContext, TLcyActionBarManager aActionBarManager)

      Returns the active settable with id aActiveSettableID from the action bar identified by aActionBarID and aActionBarContext.

      Short for: 
      
   TLcyActionBarUtil.findActiveSettable(aActiveSettableID, aActionBarManager.getActionBar(aActionBarID, aActionBarContext))
      Parameters:
      aActiveSettableID - The id of the active settable
      aActionBarID - The id of the action bar
      aActionBarContext - The context of the action bar
      aActionBarManager - The action bar manager
      Returns:
      the active settable with the specified id from the action bar, or null when not found
      Since:
      2014.0
      See Also:

    • findActiveSettable

      public static ILcyActiveSettable findActiveSettable(String aActiveSettableID, ILcyActionBar aActionBar)

      Method which loops over all active settables present in aActionBar, and returns the active settable with value aActiveSettableID for the key ID_KEY.

      Parameters:
      aActiveSettableID - The id of the searched active settable
      aActionBar - The action bar to search
      Returns:
      The active settable with the specified id, or null when no such active settable exists in aActionBar.
      Since:
      2014.0
      See Also:

    • getConfiguredActionBarIDs

      public static String[] getConfiguredActionBarIDs(ALcyProperties aConfiguration, String aID)

      Searches the given configuration for the ID's of the action bars in which an action with the given ID would be inserted.

      For instance, if the the id is 'YourAddOn.yourAction', and the configuration contains following keys:

      
 YourAddOn.yourAction.fooBar.item=...
 ...
 YourAddOn.yourAction.yourActionBar.item=...
 ...
 YourAddOn.yourAction.menuBar.item=...
 ...

      Then the returned ids would be {"fooBar", "yourActionBar", "menuBar"}.

      Parameters:
      aConfiguration - The configuration in which to look for the action bar IDs. It must not be null.
      aID - The ID of the action or active settable for which to retrieve the configured action bars. It must not be null. Note that is should be the ID of the action or active settable without the trailing dot.
      Returns:
      An array containing the IDs of the action bars found in the configuration. It is never null. It may be an empty array with length zero.

    • insertInConfiguredActionBars

      public static void insertInConfiguredActionBars(ILcdAction aAction, Object aContext, TLcyActionBarManager aActionBarManager, ALcyProperties aConfiguration)

      Inserts the given action in all the configured action bars. The IDs of the configured action bars (e.g. 'menuBar', 'toolBar') are retrieved using the getConfiguredActionBarIDs method. The 'ActionID' of the action or active settable itself (that is, the ID passed to getConfiguredActionBarIDs) is taken from the given ILcdAction using aAction.getValue(ID_KEY). So the properties to configure an action could for example look like this: 

      
 ActionID.menuBar.item            = Menu, Action
 ActionID.menuBar.groups          = MenuGroup, ActionGroup
 ActionID.menuBar.acceleratorKey  = ctrl A
 ActionID.menuBar.smallIcon       = someIcon.png

 ActionID.toolBar.item            = Action
 ActionID.toolBar.groups          = ActionGroup
 ActionID.toolBar.smallIcon       = someLargerIcon.png

      which inserts the action into the bar named 'menuBar' and into the bar named 'toolBar'. In the 'menuBar' the action is in the sub-menu 'Menu' and has an accelerator key. On the 'toolBar', the action is represented using a larger icon 'someLargerIcon.png'.

      The given ILcdAction is not inserted directly, but instead wrapped by another ILcdAction that prevents the values set with putValue on the wrapper action to be set on the original action. Since these values determine the name, icon, short description etc. of the action, wrapping the original action allows it to be configured to look different in the different menu and tool bars.

      Parameters:
      aAction - The action to insert into the configured action bars. It must not be null. It must have a unique ID as value for the ID_KEY key. This ID is used to retrieve the configured action bars (e.g. 'menuBar', 'toolBar'), as specified in getConfiguredActionBarIDs. This action is wrapped by another action to allow for different names, icons, short descriptions, ... in the different action bars.
      aContext - The context for the action bars. If this context is null, the global context is used. Refer to the TLcyActionBarManager for more details about contexts.
      aActionBarManager - The TLcyActionBarManager that should be used to retrieve the action bars. One can be retrieved using ILcyLucyEnv.getUserInterfaceManager().getActionBarManager().
      aConfiguration - The ALcyProperties instance containing the configuration of the action. Can for example be parsed from a file like this: new TLcyStringPropertiesCodec().decode("myConfigFile.cfg")
      See Also:

    • insertInConfiguredActionBars

      public static void insertInConfiguredActionBars(ILcyActiveSettable aActiveSettable, Object aContext, TLcyActionBarManager aActionBarManager, ALcyProperties aConfiguration)
      Equivalent of insertInConfiguredActionBars(ILcdAction, Object, TLcyActionBarManager, ALcyProperties) for ILcyActiveSettable.

    • insertInConfiguredActionBars

      public static void insertInConfiguredActionBars(ILcyActiveSettable aActiveSettable, Object aContext, TLcyActionBarManager aActionBarManager, ALcyProperties aConfiguration, boolean aDeactivatePossible)
      Equivalent of insertInConfiguredActionBars(ILcdAction, Object, TLcyActionBarManager, ALcyProperties) for ILcyActiveSettable.
      Parameters:
      aDeactivatePossible - Specifies whether one should be able to deactivate the given ILcyActiveSettable.

    • createGlobalProxyAction

      public static ILcdAction createGlobalProxyAction(String aActionID, String aActionBarID, TLcyActionBarManager aActionBarManager)

      Creates an action that delegates its behaviour to the action in the active context. The action is specified by the given aActionID. If no action can be found in any of the active contexts with the specified ID, the action returned by this method is disabled.

      Parameters:
      aActionID - The ID of the action to which the behaviour should be delegated. Should not be null.
      aActionBarID - The ID of the action bar in which the specified action can be found. Should not be null.
      aActionBarManager - The action bar manager in which the specified action bar can be found. Should not be null.
      Returns:
      An action whose behaviour is delegated to the action in the active context if the action can be found in that active context. Never null.
      See Also:

    • createGlobalProxyActiveSettable

      public static ILcyActiveSettable createGlobalProxyActiveSettable(String aActiveSettableID, String aActionBarID, TLcyActionBarManager aActionBarManager)

      Equivalent of createGlobalProxyAction(String, String, TLcyActionBarManager) for ILcyActiveSettable.

    • findFirstDefaultActionItem

      public static Object findFirstDefaultActionItem(ILcyActionBar aActionBar)

      Searches for the first default ILcdAction or ILcyActiveSettable in the given aActionBar. A default action has its Action.DEFAULT property set to true.

      Parameters:
      aActionBar - The ILcyActionBar in which to search for the specified ILcdAction or ILcyActiveSettable. Should not be null.
      Returns:
      The first default ILcdAction or ILcyActiveSettable if it could be found, null otherwise.

    • findActionItem

      public static Object findActionItem(String aActionID, ILcyActionBar aActionBar)

      Searches for the ILcdAction or ILcyActiveSettable corresponding to the given aActionID in the given aActionBar.

      Parameters:
      aActionID - The ID of the ILcdAction or ILcyActiveSettable for which to search. Should not be null.
      aActionBar - The ILcyActionBar in which to search for the specified ILcdAction or ILcyActiveSettable. Should not be null.
      Returns:
      The ILcdAction or ILcyActiveSettable for the given ID if it could be found, null otherwise.

    • findWrapperAction

      public static ILcdAction findWrapperAction(ILcdAction aAction, ILcyActionBar aActionBar)

      Searches for the ILcdAction corresponding to the given aAction in the given aActionBar.

      This method either returns aAction itself, a proxy action that delegates its behaviour to aAction, or null if no such actions could be found

      .
      Parameters:
      aAction - An ILcdAction for which to search. Should not be null.
      aActionBar - The ILcyActionBar in which to search for the specified ILcdAction. Should not be null.
      Returns:
      The ILcdAction for the given aAction if it could be found, null otherwise.

    • findWrapperActiveSettable

      public static ILcyActiveSettable findWrapperActiveSettable(ILcyActiveSettable aActiveSettable, ILcyActionBar aActionBar)

      Searches for the ILcyActiveSettable corresponding to the given aActiveSettable in the given aActionBar.

      This method either returns aActiveSettable itself, a proxy active settable that delegates its behaviour to aActiveSettable, or null if no such active settables could be found

      .
      Parameters:
      aActiveSettable - An ILcyActiveSettable for which to search. Should not be null.
      aActionBar - The ILcyActionBar in which to search for the specified ILcyActiveSettable. Should not be null.
      Returns:
      The ILcyActiveSettable for the given aActiveSettable if it could be found, null otherwise.

    • removeFromConfiguredActionBars

      public static void removeFromConfiguredActionBars(ILcdAction aAction, Object aContext, TLcyActionBarManager aActionBarManager, ALcyProperties aProperties)

      Removes the given action from all the action bars in which it would have been inserted by insertInConfiguredActionBars(ILcdAction, Object, TLcyActionBarManager, ALcyProperties).

      Parameters:
      aAction - The action to remove from the configured action bars. It must not be null. It must have a unique ID as value for the ID_KEY key. This ID is used to retrieve the configured action bars (e.g. 'menuBar', 'toolBar'), as specified in getConfiguredActionBarIDs.
      aContext - The context for the action bars. If this context is null, the global context is used. Refer to the TLcyActionBarManager for more details about contexts.
      aActionBarManager - The TLcyActionBarManager that should be used to retrieve the action bars. One can be retrieved using ILcyLucyEnv.getUserInterfaceManager().getActionBarManager().
      aProperties - The ALcyProperties instance containing the configuration of the actions. Can for example be parsed from a file like this: new TLcyStringPropertiesCodec().decode("myConfigFile.cfg")

    • removeFromConfiguredActionBars

      public static void removeFromConfiguredActionBars(ILcyActiveSettable aActiveSettable, Object aContext, TLcyActionBarManager aActionBarManager, ALcyProperties aProperties)

      Removes the given active settable from all the action bars in which it would have been inserted by insertInConfiguredActionBars(ILcyActiveSettable, Object, TLcyActionBarManager, ALcyProperties).

      Parameters:
      aActiveSettable - The active settable to remove from the configured action bars. It must not be null. It must have a unique ID as value for the ID_KEY key. This ID is used to retrieve the configured action bars (e.g. 'menuBar', 'toolBar'), as specified in getConfiguredActionBarIDs.
      aContext - The context for the action bars. If this context is null, the global context is used. Refer to the TLcyActionBarManager for more details about contexts.
      aActionBarManager - The TLcyActionBarManager that should be used to retrieve the action bars. One can be retrieved using ILcyLucyEnv.getUserInterfaceManager().getActionBarManager().
      aProperties - The ALcyProperties instance containing the configuration of the actions. Can for example be parsed from a file like this: new TLcyStringPropertiesCodec().decode("myConfigFile.cfg")