org.eclipse.emf.edit.provider
Class ItemProvider

java.lang.Object
  org.eclipse.emf.edit.provider.ItemProvider

All Implemented Interfaces:

IChangeNotifier, IDisposable, IItemColorProvider, IItemFontProvider, IItemLabelProvider, IStructuredItemContentProvider, ITreeItemContentProvider, IUpdateableItemParent

public class ItemProvider
extends java.lang.Object
implements IChangeNotifier, IDisposable, IItemLabelProvider, IItemColorProvider, IItemFontProvider, IStructuredItemContentProvider, ITreeItemContentProvider, IUpdateableItemParent

This item provider implementation is a convenient reusable base that can be used for an item provider that isn't an adapter for an EMF object. This default implementation is highly functional and is plastic enough for a wide variety of uses (as will be illustrated in the examples to come). The plasticity is the reason for providing a huge number of constructors.

The children list is implemented using ItemProvider.ItemProviderNotifyingArrayList. As a result, any modification of the collection (using the standard List interface) will automatically fire the correct call to each INotifyChangedListener in the changeNotifier. Furthermore, IUpdateableItemParent.setParent is called to update parent for the objects that are added to or removed from the list, but optionally, i.e., only if the interface is implemented---the adapterFactory is used if it isn't null.

There is also a text and an image, which can be set via setText and setImage to cause appropriate domain event notifications to be fired. The set methods use the stateless adapter signature for uniformity and to support IUpdateableItemText.setText(Object, String).

This class is useful as a convenient wrapper object to act as the input to a view, e.g.,

   viewer.setInput(new ItemProvider(text, image, collection));
 

lets you take a mixed collection of model objects and item providers, and show it as the elements of a structured view, i.e., as the visible roots of the view. Although a structured viewer does not show it's input object within the view, it does show the input object on the pane title. The above pattern allows you to inject a collection or the object itself into the structured viewer and to control the pane title at the same time, e.g.,

   viewer.setInput(new ItemProvider(Collections.singleton(object)));
 

will leave the pane title blank and show the object as the root of the structured view.

One could use more of these item providers to build up a scaffolding within views. Consider the following block of code which has access to a collection of INotifyChangedListeners.

   // final Collection listeners = ...;
   // final StructuredContentViewer contentViewer = ...;
   //
   // These create the items and build up the structure.
   //
   final ItemProvider child11     = new ItemProvider(listeners, "Child 1");
   final ItemProvider child12     = new ItemProvider(listeners, "Child 2");
   final ItemProvider parent1     = new ItemProvider(listeners, "Parent 1", Arrays.asList(new Object [] {child11, child12}));
   final ItemProvider child21     = new ItemProvider(listeners, "Child 1");
   final ItemProvider child22     = new ItemProvider(listeners, "Child 2");
   final ItemProvider parent2     = new ItemProvider(listeners, "Parent 2", Arrays.asList(new Object [] {child21, child22}));
   final ItemProvider grandParent = new ItemProvider(listeners, "Grand Parent", Arrays.asList(new Object [] {parent1, parent2}));
   
   // Set the items into the visible roots of the structured content viewer.
   //
   contentViewer.setInput(new ItemProvider("Pane Tile", Collections.singleton(grandParent)));
   
   // Create some delayed actions that modify the item structure.
   //
   if (contentViewer.isControlOkToUse())
   {
     contentViewer.getControl().getDisplay().asyncExec
      (new Runnable()
       {
         public void run()
         {
           // Use standard list modification that has the effect of producing a domain event notification.
           //
           parent1.getChildren().removeAll(Arrays.asList(new Object [] {child11, child12}));
  
           contentViewer.getControl().getDisplay().asyncExec
             (new Runnable()
               {
                 public void run()
                 {
                   // This also as the effect of producing a correct a domain event notification.
                   //
                   parent2.setText("Parent 2!");
                 }
               });
          }
       });
  }
 

The structure will be displayed within the contentViewer and will then change a little bit later; the flickering should be noticeable if the viewer is set to auto expand.

Another common pattern of usage will be to inject scaffolding within an EMF structure. In the following example, a new factory is defined to replace the adapters for Company and Department so as to inject an item that acts as the child of the Company and the parent of each Department. (Normally, this would not be done with all these inner classes.)

  ItemProviderAdapterFactory myItemProviderAdapterFactory = 
    new ItemProviderAdapterFactory()
    {
      public Adapter createCompanyAdapter()
      {
        // This returns a new instance each time.
        // The instance stores an injected child that in turn will have this original object's children as its children.
        //
        return
          new CompanyItemProvider(this)
          {
            // Keep track of the new child added below company.
            //
            ItemProvider injectedChild;

            public Collection getChildren(final Object object)
            {
              // Create one on demand.
              //
              if (injectedChild == null)
              {
                injectedChild = 
                  (new ItemProvider("Injected Child")
                   {
                     public Collection getChildren(Object o)
                     {
                       // Return the department of the company. 
                       // Note that we ignore o in favour of object.
                       //
                       return ((Company)object).getDepartment();
                     }
                     public boolean hasChildren(Object o)
                     {
                       // You have to make sure you override this method to match the above.
                       //
                       return !((Company)object).getDepartment().isEmpty();
                     }
                   });
              }

              return Collections.singleton(injectedChild);
            }

            public boolean hasChildren(Object object)
            {
              // You have to make sure you override this method to match the above.
              //
              return true;
            }

            public void notifyChanged(Notification msg)
            {
              // If the departments are affected...
              //
              Company company = (Company)msg.getNotifier();
              if (msg.getStructuralFeature() == company.ePackageCompany().getCompany_Deparment())
              {
                // If there's a child around to care...
                //
                if (injectedChild != null)
                {
                  // Fire the domain event as if it came from the child.
                  //
                  // EATM TODO
                  fireNotifyChanged(injectedChild, msg.getEventType(), msg.getStructuralFeature(), msg.getOldValue(), msg.getNewValue(), msg.getPostition());
                }
              }
              else
              {
                // Behave as normal.
                //
                super.notifyChanged(msg);
              }
            }
          };
      }

      public Adapter createDepartmentAdapter()
      {
        // This is still stateless.
        //
        if (departmentItemProvider == null)
        {
          departmentItemProvider = 
            new DepartmentItemProvider(this)
            {
              public Object getParent(Object object)
              {
                // Use the stateful adapter of the containing parent to determine the injected item.
                //
                Company company = ((Department)object).getCompany();
                ITreeItemContentProvider companyAdapter = 
                  (ITreeItemContentProvider)this.adapterFactory.adapt(company, ITreeItemContentProvider.class);
                if (companyAdapter != null)
                {
                  // Get the first child of the company's adapter.
                  //
                  return companyAdapter.getChildren(company).iterator().next();
                }
                else
                {
                  return null;
                }
              }
            };
         }

         // Return the single factory instance.
         //
         return departmentItemProvider;
      }
    };
 

Nested Class Summary

class	ItemProvider.ItemProviderNotification This class implements a Notification for an ItemProvider.
class	ItemProvider.ItemProviderNotifyingArrayList<E> This class overrides the "notify" methods to fire INotifyChangedListener calls and it overrides the "inverse basic" methods to maintain referential integrity by calling IUpdateableItemParent.setParent.

Field Summary

protected AdapterFactory	adapterFactory This is the optional adapter factory that is used to get adapters for parent or child objects.
protected java.lang.Object	background This is the color returned by getBackground(Object).
protected IChangeNotifier	changeNotifier This is the optional collection used for changes to the text, parent, or children.
protected ItemProvider.ItemProviderNotifyingArrayList<java.lang.Object>	children This is the children returned by getChildren(Object).
protected java.lang.Object	font This is the font returned by getFont(Object).
protected java.lang.Object	foreground This is the color returned by getForeground(Object).
protected java.lang.Object	image This is the image returned by getImage(Object).
protected java.lang.Object	parent This is the parent returned by getParent(Object).
protected java.lang.String	text This is the text returned by getText(Object).

Fields inherited from interface org.eclipse.emf.edit.provider.IItemColorProvider

GRAYED_OUT_COLOR

Fields inherited from interface org.eclipse.emf.edit.provider.IItemFontProvider

BOLD_FONT, BOLD_ITALIC_FONT, ITALIC_FONT, NORMAL_FONT

Constructor Summary

ItemProvider()
This creates an instance with an empty text that yields no children.

ItemProvider(AdapterFactory adapterFactory)
This creates an instance with the given adapter factory and an empty text that yields no children.

ItemProvider(AdapterFactory adapterFactory, java.util.Collection<?> children)
This creates an instance with the given adapter factory that yields the given children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text)
This creates an instance with the given adapter factor and text that yields no children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text, java.util.Collection<?> children)
This creates an instance with the given adapter factory and text that yields the given children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text, java.lang.Object image)
This creates an instance with the given adapter factory, text, and image that yields no children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text, java.lang.Object image, java.util.Collection<?> children)
This creates an instance with the given adapter factory, text and image that yields the given children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text, java.lang.Object image, java.lang.Object parent)
This creates an instance with the given adapter factory, text, image, and parent that yields no children.

ItemProvider(AdapterFactory adapterFactory, java.lang.String text, java.lang.Object image, java.lang.Object parent, java.util.Collection<?> children)
This creates an instance with the given adapter factory, notifier, text, image, and parent that yields the given children.

ItemProvider(java.util.Collection<?> children)
This creates an instance with an empty text that yields the given children.

ItemProvider(java.lang.String text)
This creates an instance with the given text that yields the no children.

ItemProvider(java.lang.String text, java.util.Collection<?> children)
This creates an instance with the given text that yields the given children.

ItemProvider(java.lang.String text, java.lang.Object image)
This creates an instance with the given text and image that yields the no children.

ItemProvider(java.lang.String text, java.lang.Object image, java.util.Collection<?> children)
This creates an instance with the given text and image that yields the given children.

ItemProvider(java.lang.String text, java.lang.Object image, java.lang.Object parent)
This creates an instance with the given text, image, and parent that yields no children.

ItemProvider(java.lang.String text, java.lang.Object image, java.lang.Object parent, java.util.Collection<?> children)
This creates an instance with the given text, image, and parent that yields the given children.

Method Summary

void	addListener(INotifyChangedListener listener) This adds another listener.
Command	createCommand(java.lang.Object object, EditingDomain editingDomain, java.lang.Class<? extends Command> commandClass, CommandParameter commandParameter) This implements IEditingDomainItemProvider.createCommand(), returning the unexecutable command.
void	dispose() This is called to dispose the object.
void	fireNotifyChanged(Notification notification) This calls notifyChanged for each listener.
AdapterFactory	getAdapterFactory() This yields the optional adapter factory.
java.lang.Object	getBackground() This delegates to getBackground(this).
java.lang.Object	getBackground(java.lang.Object object) This implements IItemColorProvider.getBackground by returning background.
EList<java.lang.Object>	getChildren() This returns getChildren(this).
java.util.Collection<?>	getChildren(java.lang.Object object) This implements ITreeItemContentProvider.getChildren return children.
EList<java.lang.Object>	getElements() This returns getChildren().
java.util.Collection<?>	getElements(java.lang.Object object) This implements IStructuredItemContentProvider.getElements by returning getChildren(Object).
java.lang.Object	getFont() This delegates to getFont(this).
java.lang.Object	getFont(java.lang.Object object) This implements IItemFontProvider.getFont by returning font.
java.lang.Object	getForeground() This delegates to getForeground(this).
java.lang.Object	getForeground(java.lang.Object object) This implements IItemColorProvider.getForeground by returning foreground.
java.lang.Object	getImage() This delegates to getImage(this).
java.lang.Object	getImage(java.lang.Object object) This implements IItemLabelProvider.getImage by returning image.
java.util.Collection<CommandParameter>	getNewChildDescriptors(java.lang.Object object, EditingDomain editingDomain, java.lang.Object sibling) This implements IEditingDomainItemProvider.getNewChildDescriptors, returning an empty list.
java.lang.Object	getParent() This returns getParent(this).
java.lang.Object	getParent(java.lang.Object object) This implements ITreeItemContentProvider.getParent by returning parent.
java.lang.String	getText() This delegates to getText(this).
java.lang.String	getText(java.lang.Object object) This implements IItemLabelProvider.getText by returning text.
java.lang.String	getUpdateableText(java.lang.Object object) This implements IUpdateableItemText.getUpdateableText, although the class doesn't declare that it implements this interface.
boolean	hasChildren() This returns hasChildren(this).
boolean	hasChildren(java.lang.Object object) This implements ITreeItemContentProvider.hasChildren by simply testing whether children is empty.
void	removeListener(INotifyChangedListener listener) This removes a listener.
void	setAdapterFactory(AdapterFactory adapterFactory) This sets the optional adapter factory.
void	setBackground(java.lang.Object background) This delegates to setBackground(this, background).
void	setBackground(java.lang.Object object, java.lang.Object background) This allows background to be set.
void	setFont(java.lang.Object font) This delegates to setFont(this, font).
void	setFont(java.lang.Object object, java.lang.Object font) This allows font to be set.
void	setForeground(java.lang.Object foreground) This delegates to setForeground(this, foreground).
void	setForeground(java.lang.Object object, java.lang.Object foreground) This allows foreground to be set.
void	setImage(java.lang.Object image) This delegates to setImage(this, image).
void	setImage(java.lang.Object object, java.lang.Object image) This allows image to be set.
void	setParent(java.lang.Object parent) This calls setParent(this, parent).
void	setParent(java.lang.Object object, java.lang.Object parent) This implements IUpdateableItemParent.setParent by delegating to setParent(Object).
void	setText(java.lang.Object object, java.lang.String text) This implements IUpdateableItemText.setText, although the class doesn't declare that it implements this interface.
void	setText(java.lang.String text) This delegates to setText(this, text).
java.lang.String	toString() This returns the super result with the text appended to it.

Methods inherited from class java.lang.Object

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

Field Detail

text

protected java.lang.String text

This is the text returned by getText(Object).

image

protected java.lang.Object image

This is the image returned by getImage(Object).

font

protected java.lang.Object font

This is the font returned by getFont(Object).

foreground

protected java.lang.Object foreground

This is the color returned by getForeground(Object).

background

protected java.lang.Object background

This is the color returned by getBackground(Object).

parent

protected java.lang.Object parent

This is the parent returned by getParent(Object).

children

protected ItemProvider.ItemProviderNotifyingArrayList<java.lang.Object> children

This is the children returned by getChildren(Object).

adapterFactory

protected AdapterFactory adapterFactory

This is the optional adapter factory that is used to get adapters for parent or child objects.

changeNotifier

protected IChangeNotifier changeNotifier

This is the optional collection used for changes to the text, parent, or children.

Constructor Detail

ItemProvider

public ItemProvider()

This creates an instance with an empty text that yields no children.

ItemProvider

public ItemProvider(java.util.Collection<?> children)

This creates an instance with an empty text that yields the given children.

ItemProvider

public ItemProvider(java.lang.String text)

This creates an instance with the given text that yields the no children.

ItemProvider

public ItemProvider(java.lang.String text,
                    java.util.Collection<?> children)

This creates an instance with the given text that yields the given children.

ItemProvider

public ItemProvider(java.lang.String text,
                    java.lang.Object image)

This creates an instance with the given text and image that yields the no children.

ItemProvider

public ItemProvider(java.lang.String text,
                    java.lang.Object image,
                    java.util.Collection<?> children)

This creates an instance with the given text and image that yields the given children.

ItemProvider

public ItemProvider(java.lang.String text,
                    java.lang.Object image,
                    java.lang.Object parent)

This creates an instance with the given text, image, and parent that yields no children.

ItemProvider

public ItemProvider(java.lang.String text,
                    java.lang.Object image,
                    java.lang.Object parent,
                    java.util.Collection<?> children)

This creates an instance with the given text, image, and parent that yields the given children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory)

This creates an instance with the given adapter factory and an empty text that yields no children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text)

This creates an instance with the given adapter factor and text that yields no children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text,
                    java.lang.Object image)

This creates an instance with the given adapter factory, text, and image that yields no children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text,
                    java.lang.Object image,
                    java.lang.Object parent)

This creates an instance with the given adapter factory, text, image, and parent that yields no children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.util.Collection<?> children)

This creates an instance with the given adapter factory that yields the given children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text,
                    java.util.Collection<?> children)

This creates an instance with the given adapter factory and text that yields the given children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text,
                    java.lang.Object image,
                    java.util.Collection<?> children)

This creates an instance with the given adapter factory, text and image that yields the given children.

ItemProvider

public ItemProvider(AdapterFactory adapterFactory,
                    java.lang.String text,
                    java.lang.Object image,
                    java.lang.Object parent,
                    java.util.Collection<?> children)

This creates an instance with the given adapter factory, notifier, text, image, and parent that yields the given children. This is a fully specified instance.

Method Detail

getAdapterFactory

public AdapterFactory getAdapterFactory()

This yields the optional adapter factory.

setAdapterFactory

public void setAdapterFactory(AdapterFactory adapterFactory)

This sets the optional adapter factory.

addListener

public void addListener(INotifyChangedListener listener)

Description copied from interface: IChangeNotifier

This adds another listener.

Specified by:

addListener in interface IChangeNotifier

removeListener

public void removeListener(INotifyChangedListener listener)

Description copied from interface: IChangeNotifier

This removes a listener.

Specified by:

removeListener in interface IChangeNotifier

fireNotifyChanged

public void fireNotifyChanged(Notification notification)

Description copied from interface: IChangeNotifier

This calls notifyChanged for each listener.

Specified by:

fireNotifyChanged in interface IChangeNotifier

getElements

public java.util.Collection<?> getElements(java.lang.Object object)

This implements IStructuredItemContentProvider.getElements by returning getChildren(Object). It seems that you almost always want getElements and getChildren to return the same thing, so this makes that easy.

Specified by:

getElements in interface IStructuredItemContentProvider

getElements

public EList<java.lang.Object> getElements()

This returns getChildren(). It seems that you almost always want getElements and getChildren to return the same thing, so this makes that easy.

getChildren

public java.util.Collection<?> getChildren(java.lang.Object object)

This implements ITreeItemContentProvider.getChildren return children. You can also choose to ignore the children entirely and implement a virtual collection; In this case, you must implement notification is some other way yourself, and you should override hasChildren(Object) appropriately.

Specified by:

getChildren in interface ITreeItemContentProvider

getChildren

public EList<java.lang.Object> getChildren()

This returns getChildren(this).

hasChildren

public boolean hasChildren(java.lang.Object object)

This implements ITreeItemContentProvider.hasChildren by simply testing whether children is empty. This implementation will always be right, however, for efficiency you may want to override it to return false for a leaf item, or true for an item that always has children.

Specified by:

hasChildren in interface ITreeItemContentProvider

hasChildren

public boolean hasChildren()

This returns hasChildren(this).

getParent

public java.lang.Object getParent(java.lang.Object object)

This implements ITreeItemContentProvider.getParent by returning parent.

Specified by:

getParent in interface ITreeItemContentProvider

getParent

public java.lang.Object getParent()

This returns getParent(this).

setParent

public void setParent(java.lang.Object object,
                      java.lang.Object parent)

This implements IUpdateableItemParent.setParent by delegating to setParent(Object).

Specified by:

setParent in interface IUpdateableItemParent

setParent

public void setParent(java.lang.Object parent)

This calls setParent(this, parent).

getImage

public java.lang.Object getImage(java.lang.Object object)

This implements IItemLabelProvider.getImage by returning image.

Specified by:

getImage in interface IItemLabelProvider

getImage

public java.lang.Object getImage()

This delegates to getImage(this).

setImage

public void setImage(java.lang.Object object,
                     java.lang.Object image)

This allows image to be set. If there is a domain notifier, it fires the appropriate domain event.

setImage

public void setImage(java.lang.Object image)

This delegates to setImage(this, image).

getText

public java.lang.String getText(java.lang.Object object)

This implements IItemLabelProvider.getText by returning text.

Specified by:

getText in interface IItemLabelProvider

getText

public java.lang.String getText()

This delegates to getText(this).

getUpdateableText

public java.lang.String getUpdateableText(java.lang.Object object)

This implements IUpdateableItemText.getUpdateableText, although the class doesn't declare that it implements this interface.

setText

public void setText(java.lang.Object object,
                    java.lang.String text)

This implements IUpdateableItemText.setText, although the class doesn't declare that it implements this interface. If there is a domain notifier, it fires the appropriate domain event.

setText

public void setText(java.lang.String text)

This delegates to setText(this, text).

getFont

public java.lang.Object getFont(java.lang.Object object)

This implements IItemFontProvider.getFont by returning font.

Specified by:

getFont in interface IItemFontProvider

getFont

public java.lang.Object getFont()

This delegates to getFont(this).

setFont

public void setFont(java.lang.Object object,
                    java.lang.Object font)

This allows font to be set. If there is a domain notifier, it fires the appropriate domain event.

setFont

public void setFont(java.lang.Object font)

This delegates to setFont(this, font).

getForeground

public java.lang.Object getForeground(java.lang.Object object)

This implements IItemColorProvider.getForeground by returning foreground.

Specified by:

getForeground in interface IItemColorProvider

getForeground

public java.lang.Object getForeground()

This delegates to getForeground(this).

setForeground

public void setForeground(java.lang.Object object,
                          java.lang.Object foreground)

This allows foreground to be set. If there is a domain notifier, it fires the appropriate domain event.

setForeground

public void setForeground(java.lang.Object foreground)

This delegates to setForeground(this, foreground).

getBackground

public java.lang.Object getBackground(java.lang.Object object)

This implements IItemColorProvider.getBackground by returning background.

Specified by:

getBackground in interface IItemColorProvider

getBackground

public java.lang.Object getBackground()

This delegates to getBackground(this).

setBackground

public void setBackground(java.lang.Object object,
                          java.lang.Object background)

This allows background to be set. If there is a domain notifier, it fires the appropriate domain event.

setBackground

public void setBackground(java.lang.Object background)

This delegates to setBackground(this, background).

toString

public java.lang.String toString()

This returns the super result with the text appended to it.

Overrides:

toString in class java.lang.Object

dispose

public void dispose()

Description copied from interface: IDisposable

This is called to dispose the object.

Specified by:

dispose in interface IDisposable

getNewChildDescriptors

public java.util.Collection<CommandParameter> getNewChildDescriptors(java.lang.Object object,
                                                                     EditingDomain editingDomain,
                                                                     java.lang.Object sibling)

This implements IEditingDomainItemProvider.getNewChildDescriptors, returning an empty list.

createCommand

public Command createCommand(java.lang.Object object,
                             EditingDomain editingDomain,
                             java.lang.Class<? extends Command> commandClass,
                             CommandParameter commandParameter)

This implements IEditingDomainItemProvider.createCommand(), returning the unexecutable command.