Compared to classic object-oriented concepts, the look-up idiom enables a dynamism that would be hard (or at least tedious) to achieve using either subclassing or interface implementations. In particular, it can be used to easily add new "aspects" to the model items in a graph without having to subclass and implement yet another set of interfaces.

Also, the behavior of model items can be modified at runtime by simply changing their look-up to return either customized logic for some requested type, or the default, or nothing at all. Example 5.1, “Dynamically changing the behavior of model items” presents this use-case building on the general support for look-up customization described below.

The same technique can also be observed in the section called “Customizing User Interaction Behavior”, which discusses customization of user interaction behavior by decorating the look-up of model items. More importantly, this section also lists the type requests that are supported by model item types in the context of user gesture handling.

void EnableCustomLookupBehavior(IGraph graph, bool enable) {
  // Get the graph's ILookupDecorator that enables manipulation of all look-up 
  // operations for the contained graph elements.
  ILookupDecorator decorator = graph.Get<ILookupDecorator>();
  if (decorator != null) {
    // Test whether decoration of look-up operations initiated on type INode is 
    // supported.
    if (decorator.CanDecorate(typeof (INode))) {
      if (enable) {
        // Prepend a custom look-up provider.
        decorator.AddLookup(typeof (INode), CustomReshapeableChainLink);
      }
      else {
        // Remove the custom look-up provider.
        decorator.RemoveLookup(typeof (INode), CustomReshapeableChainLink);
      }
    }
  }
}

IContextLookupChainLink CustomReshapeableChainLink {
  get { return customReshapeableChainLink; }
}

Look-up chaining describes the technique of combining an arbitrary number of look-up providers in a daisy-chain manner: implementations of interface IContextLookupChainLink are linked together via their SetNext method.

Whenever such a look-up chain is queried for a specific type and a look-up provider would fail to return a proper instance, instead of returning null, it delegates to its successor in the look-up chain. Thus, the successor's look-up facility is queried for the given type, and so on until either a look-up provider is able to satisfy the request or the last element in the look-up chain returns null.

Most prominently, class DefaultGraph, which presents the default graph structure implementation, uses look-up chaining.

Look-up chaining paves the way for convenient manipulation of look-up operations, respectively their return values. By simply prepending a look-up provider to an existing look-up chain, default behavior can be easily customized: a prepended chain link element is able to handle specific types while letting pass those that it is not interested in. For the type requests it handles, it can return modified instances that provide custom logic.

Adding a look-up chain link to a model item type, for example, can be seen as dynamically subclassing the model item type in question, but only for the instances used in this context and then overriding just the Lookup(Type) method of the INode, IEdge, ILabel, etc. type. The difference is that the "this" is passed in as a parameter in the Lookup method of the chain link.

The added look-up chain link effectively overrides the implementations present in the look-up of the model item type for a specific type request. Adding more look-up chain links to a type is like subclassing more and more, so the order in which chain links are added matters.

Interface ILookupDecorator defines the functionality that enables manipulating look-up chains related to given types. The following methods of ILookupDecorator can be used to modify a type's look-up chain:

bool CanDecorate(Type t)

void AddLookup(Type t, IContextLookupChainLink lookup)
void RemoveLookup(Type t, IContextLookupChainLink lookup)

Generic utility class LookupDecorator<TDecoratedType, TInterface> enables convenient decoration of look-up chains on top of a given ILookupDecorator. The type parameters specify the context for which a LookupDecorator instance is created: first the type whose look-up chain will be customized, then the interface type in the look-up chain that will be affected. Example 5.3, “Instantiating LookupDecorator using a given ILookupDecorator” presents how to create a LookupDecorator instance for the nodes in a graph.

// 'graph' is of type yWorks.yFiles.UI.Model.IGraph.

ILookupDecorator decorator = graph.Get<ILookupDecorator>();
LookupDecorator<INode, IHandleProvider> handleDecorator = 
    new LookupDecorator<INode, IHandleProvider>(decorator, true, false);

The following methods from class LookupDecorator enable instant modifications to the look-up chain of the decorated type:

IContextLookupChainLink HideImplementation()
IContextLookupChainLink HideImplementation(Predicate<TDecoratedType> predicate)

IContextLookupChainLink SetImplementation(
    TDecoratedType forItem, TInterface implementation)
IContextLookupChainLink SetImplementation(
    Predicate<TDecoratedType> predicate, TInterface implementation)

IContextLookupChainLink SetFactory(
    FactoryDelegate<TInterface, TDecoratedType> factory)
IContextLookupChainLink SetFactory(
    Predicate<TDecoratedType> predicate,
    FactoryDelegate<TInterface, TDecoratedType> factory)

IContextLookupChainLink SetImplementationWrapper(
    WrapperFactory<TDecoratedType, TInterface> factory)
IContextLookupChainLink SetImplementationWrapper(
    Predicate<TDecoratedType> predicate,
    WrapperFactory<TDecoratedType, TInterface> factory)

Most prominently, class DefaultGraph, which presents the default graph structure implementation, uses look-up chaining. It supports decoration of the look-up chains it is maintaining for model item types through an ILookupDecorator implementation that can be requested via its Lookup method as well as through the model item-specific decorators that are made available by the GraphDecorator class.

Example 5.4, “Look-up chain modification using class GraphDecorator” shows an excerpt from the GraphEditorWindow demo application where the GraphDecorator class is used to conveniently decorate the look-up chain of nodes.

// 'graph' is of type yWorks.yFiles.UI.Model.IGraph.

var graphDecorator = Graph.GetDecorator();
var nodeDecorator = graphDecorator.NodeDecorator;
// We use the size of the labels for group node insets.
nodeDecorator.InsetsProviderDecorator.SetImplementationWrapper(
    (node, baseImplementation) => 
        new LabelInsetsProvider<INode>(baseImplementation)
);

// Add custom node size constraints that consider labels that are stretched 
// inside the node.
nodeDecorator.SizeConstraintProviderDecorator.SetImplementationWrapper(
    (item, implementation) => 
        new LabelSizeConstraintProvider<INode>(implementation)
);

The tutorial demo applications that present user interaction customization, like, e.g., PositionHandlerWindow, show how interactive behavior of model items in a DefaultGraph can be customized using the services of ILookupDecorator. Further demos that use an ILookupDecorator include: