IBaseLabelProvider


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.jface.viewers;
12  
13  /**
14   * A label provider maps an element of the viewer's model to
15   * an optional image and optional text string used to display
16   * the element in the viewer's control.  Certain label providers
17   * may allow multiple labels per element.  
18   * This is an "abstract interface", defining methods common 
19   * to all label providers, but does not actually define the methods 
20   * to get the label(s) for an element.  This interface should never
21   * be directly implemented.
22   * Most viewers will take either an <code>ILabelProvider</code> or
23   * an <code>ITableLabelProvider</code>.
24   * <p>
25   * A label provider must not be shared between viewers 
26   * since a label provider generally manages SWT resources (images),
27   * which must be disposed when the viewer is disposed.
28   * To simplify life cycle management, the current label provider 
29   * of a viewer is disposed when the viewer is disposed.
30   * </p>
31   * <p>
32   * Label providers can be used outside the context of viewers wherever
33   * images are needed.  When label providers are used in this fashion
34   * it is the responsibility of the user to ensure <code>dispose</code>
35   * is called when the provider is no longer needed.
36   * </p>
37   *
38   * @see ILabelProvider
39   * @see ITableLabelProvider
40   */
41  public interface IBaseLabelProvider {
42      /**
43       * Adds a listener to this label provider. 
44       * Has no effect if an identical listener is already registered.
45       * <p>
46       * Label provider listeners are informed about state changes 
47       * that affect the rendering of the viewer that uses this label provider.
48       * </p>
49       *
50       * @param listener a label provider listener
51       */
52      public void addListener(ILabelProviderListener listener);
53  
54      /**
55       * Disposes of this label provider.  When a label provider is
56       * attached to a viewer, the viewer will automatically call
57       * this method when the viewer is being closed.  When label providers
58       * are used outside of the context of a viewer, it is the client's
59       * responsibility to ensure that this method is called when the
60       * provider is no longer needed.
61       */
62      public void dispose();
63  
64      /**
65       * Returns whether the label would be affected 
66       * by a change to the given property of the given element.
67       * This can be used to optimize a non-structural viewer update.
68       * If the property mentioned in the update does not affect the label,
69       * then the viewer need not update the label.
70       *
71       * @param element the element
72       * @param property the property
73       * @return <code>true</code> if the label would be affected,
74       *    and <code>false</code> if it would be unaffected
75       */
76      public boolean isLabelProperty(Object   element, String   property);
77  
78      /**
79       * Removes a listener to this label provider.
80       * Has no affect if an identical listener is not registered.
81       *
82       * @param listener a label provider listener
83       */
84      public void removeListener(ILabelProviderListener listener);
85  }
86
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags