| # GUI Commands User Guide ## Version 2.1 |
| # 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: Components that supply delegates must implement `DelegateProvider`. Create and bind your DelegatingCommands. 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);