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