Bug 74337 FieldEditor should document that doFillIntoGrid() is called from the superclass constructor.
The doFillIntoGrid() method is called from the constructor of the FieldEditor class. This should REALLY be documented. It cost me 3 hours of work on a nasty bug. Consider the following addition to the documentation: --------------------------------------------------------------------------- <p> Developers should be aware that FieldEditor calls the doFillIntoGrid() method in its constructor. The significance of this can be demonstrated by the following snippet. </p> <pre> public class RegexPatternSetFieldEditor extends FieldEditor implements SelectionListener,IDoubleClickListener { // .... snip /** The sorted set of patterns. */ private final SortedSet patterns = new TreeSet(new RegexSortingComparator()); // .... snip public RegexPatternSetFieldEditor(final String preferenceName, final String labelText, final Composite parent) { super(preferenceName, labelText, parent); } // .... snip protected void doFillIntoGrid(final Composite parent, final int numColumns) { // .... snip this.tbvPatternList = new TableViewer(table); this.tbvPatternList.setLabelProvider(new RegexPatternLabelProvider()); this.tbvPatternList.setContentProvider( new RegexPatternsContentProvider()); this.tbvPatternList.setInput(this.patterns); // .... snip } } </pre> <p> In this case the user just set <b><code>null</code></b> as input to the table viewer, <code>tbvPatternList</code>. Once you know that this method is called from the superclass constructor, it is self-evident why. Constructors are run before initializers and therefore at the time that the constructor is calling super, <code>this.patterns</code> is <code>null<code>. However, microseconds later when the call to the <code>doFillIntoGrid()</code> is done, the initializers are run. The result is that the viewer is looking at <code>null</code> and yet this.patterns is not null. </p> ---------------------------------------------------------------------------
bundles/org.eclipse.jface/src/org/eclipse/jface/preference/FieldEditor.java
/**
     * Fills this field editor's basic controls into the given parent.
     * <p>
     * Subclasses must implement this method to create the controls
     * for this field editor.
     * </p>
     *
     * @param parent the composite used as a parent for the basic controls;
     *	the parent's layout must be a <code>GridLayout</code>
     * @param numColumns the number of columns
     */
    protected abstract void doFillIntoGrid(Composite parent, int numColumns);
    /**
     * Initializes this field editor with the preference value from
     * the preference store.
     * <p>
     * Subclasses must implement this method to properly initialize 
     * the field editor.
     * </p>
     */
    protected abstract void doLoad();
    /**
     * Initializes this field editor with the default preference value from
     * the preference store.
     * <p>
     * Subclasses must implement this method to properly initialize 
     * the field editor.
     * </p>
     */
    protected abstract void doLoadDefault();