IPropertySource


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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   *     Gunnar Wagenknecht - fix for bug 21756 (https://bugs.eclipse.org/bugs/show_bug.cgi?id=21756)
11   *******************************************************************************/
12  package org.eclipse.ui.views.properties;
13  
14  /**
15   * Interface to an object which is capable of supplying properties for display
16   * by the standard property sheet page implementation (<code>PropertySheetPage</code>).
17   * <p>
18   * This interface should be implemented by clients.
19   * <code>PropertySheetPage</code> discovers the properties to display from
20   * currently selected elements. Elements that implement
21   * <code>IPropertySource</code> directly are included, as are elements that
22   * implement <code>IAdaptable</code> and have an <code>IPropertySource</code>
23   * adapter. Clients should implement this interface for any newly-defined
24   * elements that are to have properties displayable by
25   * <code>PropertySheetPage</code>. Note that in the latter case, the client
26   * will also need to register a suitable adapter factory with the platform's
27   * adapter manager (<code>Platform.getAdapterManager</code>).
28   * </p>
29   * 
30   * @see org.eclipse.core.runtime.IAdaptable
31   * @see org.eclipse.core.runtime.Platform#getAdapterManager()
32   * @see org.eclipse.ui.views.properties.PropertySheetPage
33   * @see org.eclipse.ui.views.properties.IPropertySource2
34   */
35  public interface IPropertySource {
36  
37      /**
38       * Returns a value for this property source that can be edited in a property
39       * sheet.
40       * <p>
41       * This value is used when this <code>IPropertySource</code> is appearing
42       * in the property sheet as the value of a property of some other
43       * <code>IPropertySource</code>
44       * </p>
45       * <p>
46       * This value is passed as the input to a cell editor opening on an
47       * <code>IPropertySource</code>.
48       * </p>
49       * <p>
50       * This value is also used when an <code>IPropertySource</code> is being
51       * used as the value in a <code>setPropertyValue</code> message. The
52       * reciever of the message would then typically use the editable value to
53       * update the original property source or construct a new instance.
54       * </p>
55       * <p>
56       * For example an email address which is a property source may have an
57       * editable value which is a string so that it can be edited in a text cell
58       * editor. The email address would also have a constructor or setter that
59       * takes the edited string so that an appropriate instance can be created or
60       * the original instance modified when the edited value is set.
61       * </p>
62       * <p>
63       * This behavior is important for another reason. When the property sheet is
64       * showing properties for more than one object (multiple selection), a
65       * property sheet entry will display and edit a single value (typically
66       * coming from the first selected object). After a property has been edited
67       * in a cell editor, the same value is set as the property value for all of
68       * the objects. This is fine for primitive types but otherwise all of the
69       * objects end up with a reference to the same value. Thus by creating an
70       * editable value and using it to update the state of the original property
71       * source object, one is able to edit several property source objects at
72       * once (multiple selection).
73       * 
74       * @return a value that can be edited
75       */
76      public Object   getEditableValue();
77  
78      /**
79       * Returns the list of property descriptors for this property source. The
80       * <code>getPropertyValue</code> and <code>setPropertyValue</code>
81       * methods are used to read and write the actual property values by
82       * specifying the property ids from these property descriptors.
83       * <p>
84       * Implementors should cache the descriptors as they will be asked for the
85       * descriptors with any edit/update. Since descriptors provide cell editors,
86       * returning the same descriptors if possible allows for efficient updating.
87       * </p>
88       * 
89       * @return the property descriptors
90       */
91      public IPropertyDescriptor[] getPropertyDescriptors();
92  
93      /**
94       * Returns the value of the property with the given id if it has one.
95       * Returns <code>null</code> if the property's value is <code>null</code>
96       * value or if this source does not have the specified property.
97       * 
98       * @see #setPropertyValue
99       * @param id
100      *            the id of the property being set
101      * @return the value of the property, or <code>null</code>
102      */
103     public Object   getPropertyValue(Object   id);
104 
105     /**
106      * Returns whether the value of the property with the given id has changed
107      * from its default value. Returns <code>false</code> if this source does
108      * not have the specified property.
109      * <p>
110      * If the notion of default value is not meaningful for the specified
111      * property then <code>false</code> is returned.
112      * </p>
113      * 
114      * @param id
115      *            the id of the property
116      * @return <code>true</code> if the value of the specified property has
117      *         changed from its original default value, <code>false</code> if
118      *         the specified property does not have a meaningful default value,
119      *         and <code>false</code> if this source does not have the
120      *         specified property
121      * @see IPropertySource2#isPropertyResettable(Object)
122      * @see #resetPropertyValue(Object)
123      */
124     public boolean isPropertySet(Object   id);
125 
126     /**
127      * Resets the property with the given id to its default value if possible.
128      * <p>
129      * Does nothing if the notion of a default value is not meaningful for the
130      * specified property, or if the property's value cannot be changed, or if
131      * this source does not have the specified property.
132      * </p>
133      * <p>
134      * Callers will check if this <code>IPropertySource</code> implements
135      * <code>IPropertySource2</code> and this method will only be called if
136      * <code>IPropertySource2#isPropertyResettable(Object)</code> returns
137      * <code>true</code> for the property with the given id.
138      * </p>
139      * 
140      * @param id
141      *            the id of the property being reset
142      * @see #isPropertySet(Object)
143      * @see IPropertySource2#isPropertyResettable(Object)
144      */
145     public void resetPropertyValue(Object   id);
146 
147     /**
148      * Sets the property with the given id if possible. Does nothing if the
149      * property's value cannot be changed or if this source does not have the
150      * specified property.
151      * <p>
152      * In general, a property source should not directly reference the value
153      * parameter unless it is an atomic object that can be shared, such as a
154      * string.
155      * </p>
156      * <p>
157      * An important reason for this is that several property sources with
158      * compatible descriptors could be appearing in the property sheet at the
159      * same time. An editor produces a single edited value which is passed as
160      * the value parameter of this message to all the property sources. Thus to
161      * avoid a situation where all of the property sources reference the same
162      * value they should use the value parameter to create a new instance of the
163      * real value for the given property.
164      * </p>
165      * <p>
166      * There is another reason why a level of indirection is useful. The real
167      * value of property may be a type that cannot be edited with a standard
168      * cell editor. However instead of returning the real value in
169      * <code>getPropertyValue</code>, the value could be converted to a
170      * <code>String</code> which could be edited with a standard cell editor.
171      * The edited value will be passed to this method which can then turn it
172      * back into the real property value.
173      * </p>
174      * <p>
175      * Another variation on returning a value other than the real property value
176      * in <code>getPropertyValue</code> is to return a value which is an
177      * <code>IPropertySource</code> (or for which the property sheet can
178      * obtain an <code>IPropertySource</code>). In this case the value to
179      * edit is obtained from the child property source using
180      * <code>getEditableValue</code>. It is this editable value that will be
181      * passed back via this method when it has been editted
182      * </p>
183      * 
184      * @see #getPropertyValue
185      * @see #getEditableValue
186      * @param id
187      *            the id of the property being set
188      * @param value
189      *            the new value for the property; <code>null</code> is allowed
190      */
191     public void setPropertyValue(Object   id, Object   value);
192 }
193
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags