Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "FAQ How do I use properties to optimize a viewer?"
m |
|||
Line 6: | Line 6: | ||
154 classes and 1,105 methods contain the word <i>property</i> | 154 classes and 1,105 methods contain the word <i>property</i> | ||
in the Eclipse SDK code base. | in the Eclipse SDK code base. | ||
− | |||
− | |||
− | |||
In the context of JFace viewers, <i>property</i> means any aspect | In the context of JFace viewers, <i>property</i> means any aspect | ||
Line 14: | Line 11: | ||
Concretely, this means that whenever a property changes, the visual presentation | Concretely, this means that whenever a property changes, the visual presentation | ||
of the viewer has to be updated in some way. | of the viewer has to be updated in some way. | ||
− | |||
− | |||
The interface <tt>IBasicPropertyConstants</tt> | The interface <tt>IBasicPropertyConstants</tt> | ||
Line 26: | Line 21: | ||
You could define a set of domain-specific properties for | You could define a set of domain-specific properties for | ||
that viewer to enumerate all these values: | that viewer to enumerate all these values: | ||
+ | |||
<pre> | <pre> | ||
public interface IAncestralConstants { | public interface IAncestralConstants { | ||
Line 34: | Line 30: | ||
} | } | ||
</pre> | </pre> | ||
+ | |||
Note that a property doesn’t necessarily represent something that is | Note that a property doesn’t necessarily represent something that is | ||
directly visible but rather something that affects the presentation in some way. | directly visible but rather something that affects the presentation in some way. | ||
− | |||
− | |||
− | |||
The label provider, filters, and sorters associated with the viewer define | The label provider, filters, and sorters associated with the viewer define | ||
Line 44: | Line 38: | ||
cares only about the name and birth year, so it would override the | cares only about the name and birth year, so it would override the | ||
<tt>isLabelProperty</tt> method on <tt>IBaseLabelProvider</tt> as follows: | <tt>isLabelProperty</tt> method on <tt>IBaseLabelProvider</tt> as follows: | ||
+ | |||
<pre> | <pre> | ||
public boolean isLabelProperty(Object el, String prop) { | public boolean isLabelProperty(Object el, String prop) { | ||
Line 50: | Line 45: | ||
} | } | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
Similarly, a sorter that sorts entries by name would override | Similarly, a sorter that sorts entries by name would override | ||
Line 59: | Line 51: | ||
a subset based on hair color would override <tt>ViewerFilter.isFilterProperty</tt> to | a subset based on hair color would override <tt>ViewerFilter.isFilterProperty</tt> to | ||
return <tt>true</tt> only for the <tt>HAIR_COLOR</tt> property. | return <tt>true</tt> only for the <tt>HAIR_COLOR</tt> property. | ||
− | |||
− | |||
− | |||
Still not seeing the point of all this? Well, here’s the interesting bit. When | Still not seeing the point of all this? Well, here’s the interesting bit. When | ||
changes are made to the domain objects, the viewer’s | changes are made to the domain objects, the viewer’s | ||
− | <tt>update</tt> method, defined | + | <tt>update</tt> method, defined on <tt>StructuredViewer</tt>, |
+ | can be passed a set of properties to help it optimize the update: | ||
− | |||
− | |||
<pre> | <pre> | ||
viewer.update(person, new String[] {NAME}); | viewer.update(person, new String[] {NAME}); | ||
viewer.update(person, new String[] {GENDER, HAIR_COLOR}); | viewer.update(person, new String[] {GENDER, HAIR_COLOR}); | ||
</pre> | </pre> | ||
− | |||
− | |||
− | |||
The viewer update algorithm will ask the label provider and any installed | The viewer update algorithm will ask the label provider and any installed | ||
Line 83: | Line 68: | ||
update is very fast. If any sorter or filter is affected by the change, | update is very fast. If any sorter or filter is affected by the change, | ||
significant work has to be done to update the view. | significant work has to be done to update the view. | ||
− | |||
− | |||
You can ignore this | You can ignore this | ||
Line 92: | Line 75: | ||
or filters attached to it. For a viewer that contains a large number of values, | or filters attached to it. For a viewer that contains a large number of values, | ||
the speedup from using properties can be significant. | the speedup from using properties can be significant. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
== See Also: == | == See Also: == | ||
+ | *[[FAQ What is a viewer?]] | ||
− | + | {{Template:FAQ_Tagline}} | |
− | + | ||
− | + | ||
− | + |
Latest revision as of 21:45, 29 May 2006
The word property is one of those unfortunate programming terms that is overused because it can mean just about anything. The downside of using such a semantically weak term is that in different contexts it can mean very different things. The Eclipse Project certainly does not escape this foible: At the time of this writing, 154 classes and 1,105 methods contain the word property in the Eclipse SDK code base.
In the context of JFace viewers, property means any aspect that has relevance to how the domain objects being displayed are presented. Concretely, this means that whenever a property changes, the visual presentation of the viewer has to be updated in some way.
The interface IBasicPropertyConstants defines some simple properties—parent, children, text, and image—but the set of possible properties is open ended. Let’s say, for example, that you have a tree viewer that is showing a person’s ancestral tree. The label of each tree item may contain different information, such as the person’s name and year of birth. The viewer may have several filters for showing subsets of the family tree, such as gender or hair color. You could define a set of domain-specific properties for that viewer to enumerate all these values:
public interface IAncestralConstants { public static final String BIRTH_YEAR = "birth-year"; public static final String NAME = "name"; public static final String GENDER = "gender"; public static final String HAIR_COLOR= "hair-color"; }
Note that a property doesn’t necessarily represent something that is directly visible but rather something that affects the presentation in some way.
The label provider, filters, and sorters associated with the viewer define which properties affect them. In this case, the label provider cares only about the name and birth year, so it would override the isLabelProperty method on IBaseLabelProvider as follows:
public boolean isLabelProperty(Object el, String prop) { return IAncestralConstants.NAME.equals(prop) || IAncestralConstants.BIRTH_YEAR.equals(prop); }
Similarly, a sorter that sorts entries by name would override the method ViewerSorter.isSorterProperty to return true only for the NAME property. A filter that defines a subset based on hair color would override ViewerFilter.isFilterProperty to return true only for the HAIR_COLOR property.
Still not seeing the point of all this? Well, here’s the interesting bit. When changes are made to the domain objects, the viewer’s update method, defined on StructuredViewer, can be passed a set of properties to help it optimize the update:
viewer.update(person, new String[] {NAME}); viewer.update(person, new String[] {GENDER, HAIR_COLOR});
The viewer update algorithm will ask the label provider and any installed sorter and filters whether they are affected by the property being changed. This information can allow the update method to make some very significant optimizations. If the sorter and filters are not affected by the change, the update is very fast. If any sorter or filter is affected by the change, significant work has to be done to update the view.
You can ignore this whole mechanism by passing null as the properties to the update method, but it means that a complete refresh will happen on every update. Resist the temptation to do this, especially if your viewer will ever have sorters or filters attached to it. For a viewer that contains a large number of values, the speedup from using properties can be significant.
See Also:
This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.