Delegates Example

This example demonstrates the use a FocusTrackingDelegateMediator to automatically maintain the set of delegates from the hierarchy of the focused component. The process involves the following 3 steps:

  1. Components that supply delegates must implement DelegateProvider.
  2. Create and bind your DelegatingCommands.
  3. Create a FocusTrackingDelegateMediator and add it to your main CommandContainer.

The mediator will then traverse the hierarchy finding all components that implement DelegateProvider. These are then used to determine the current set of delegates.

1. Create your Delegates and implement DelegateProvider

First we create our delegates and have our component implement DelegateProvider.

   public ComponentWithDelegates
   extends JPanel
   implements DelegateProvider
   {
      private DelegateProviderSupport delegates = new DelegateProviderSupport();

      public ComponentWithDelegates()
      {
         // create and add our delegates.
         ActionCommandDelegate cutDelegate = new CutDelegate("cut");
         ActionCommandDelegate copyDelegate = new CopyDelegate("copy");
         ActionCommandDelegate cutDelegate = new PasteDelegate("paste");

         delegates.add(cutDelegate, copyDelegate, cutDelegate);
      }

      /**
       * Implement DelegateProvider
       */
      public ActionCommandExecutor getActionCommandExecutor(String id)
      {
         // simply delegate to our delegate support.
         return delegates.getActionCommandExecutor(id);
      }
   }
NOTE: In the above example we use a DelegateProviderSupport to manage our delegates. You can also use a CommandContainer in the same way since it too implements DelegateProvider and will vend any commands or delegates bound to it.

2. Create your DelegatingCommands

Here we create the DelegatingCommands and bind them to the main container. These commands will invoke the delegates created above.

   // This is the long and hard way...
   new DelegatingCommand("cut").bind(frameContainer);
   new DelegatingCommand("copy").bind(frameContainer);
   new DelegatingCommand("paste").bind(frameContainer);

Since the above is highly repetitive, DelegatingCommand provides static methods for creating and binding multiple delegates at once. The following is the preferred way of creating DelegatingCommands:

   // This is much simpler than the above.
   DelegatingCommand.bindAll(frameContainer, "cut", "copy", "paste");

3. Install the Delegate Mediator

Now we create our focus tracking mediator and install it on the frame's command container.

   JFrame frame = ...;
   CommandContainer frameContainer = ...;

   // create a mediator for the current frame.
   DelegateMediator mediator = new FocusTrackingDelegateMediator(frame);

   // and set it on the frames container.
   frameContainer.setDelegateMediator(mediator);

The DelegatingCommands will now be automatically configured when ever an instance of ComponentWithDelegates is within the focus hierarchy.

Setting Baseline Delegates

There will often be cases where the current set of delegates consists of both a static set of delegates, and a set derived from the focus hierarchy. For this reason the FocusTrackingDelegateMediator allows you to configure a set of static delegates that will be used regardless of the current focus state. The focus dependent delegates are given precedence over the static delegates. This allows you to provide a baseline behaviour that can be overridden by individual components as required.

The following is an example:

   FocusTrackingDelegateMediator mediator = ...;
   // set the baseline delegates..
   mediator.setBaselineDelegates(defaultCutDelegate,
                                 defaultCopyDelegate,
                                 defaultPasteDelegate);

Custom Delegate Mediation

The DefaultDelegateMediator is usefull when the FocusTrackingDelegateMediator doesn't meet your needs. In this case you need to configure the mediator directly whenever you require the delegates to update.

1. Create and Install the Mediator

The mediator is created and installed on the top level container as normal.

   CommandContainer frameContainer = ...;
   DefaultDelegateMediator delegateMediator = new DefaultDelegateMediator();

   frameContainer.setDelegateMediator(delegateMediator);

2. Manually Install the Delegates

Delegates can then be manually added to the mediator. You can also specify one or more DelegateContainers as the source of delegates.

   // Create some delegates...
   DelegatingCommand cutDelegate = new DelegatingCommand("cut");
   DelegatingCommand copyDelegate = new DelegatingCommand("copy");
   DelegatingCommand pasteDelegate = new DelegatingCommand("paste");

   // Manually configure the mediator with the delegates...
   delegateMediator.setDelegates(cutDelegate, copyDelegate, pasteDelegate);