org.eclipse.jface.preference.FieldEditor Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.jface.preference;
import org.eclipse.jface.dialogs.DialogPage;
import org.eclipse.jface.dialogs.IDialogConstants;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.core.runtime.Assert;
import org.eclipse.jface.util.IPropertyChangeListener;
import org.eclipse.jface.util.PropertyChangeEvent;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.FontMetrics;
import org.eclipse.swt.graphics.GC;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Label;
/**
* Abstract base class for all field editors.
*
* A field editor presents the value of a preference to the end
* user. The value is loaded from a preference store; if
* modified by the end user, the value is validated and eventually
* stored back to the preference store. A field editor reports
* an event when the value, or the validity of the value, changes.
*
*
* Field editors should be used in conjunction with a field
* editor preference page (FieldEditorPreferencePage)
* which coordinates everything and provides the message line
* which display messages emanating from the editor.
*
*
* This package contains ready-to-use field editors for various
* types of preferences:
*
* BooleanFieldEditor - booleansIntegerFieldEditor - integersStringFieldEditor - text stringsRadioGroupFieldEditor - enumerationsColorFieldEditor - RGB colorsFontFieldEditor - fontsDirectoryFieldEditor - directoriesFileFieldEditor - filesPathEditor - paths
*
*/
public abstract class FieldEditor {
/**
* Property name constant (value "field_editor_is_valid")
* to signal a change in the validity of the value of this field editor.
*/
public static final String IS_VALID = "field_editor_is_valid";//$NON-NLS-1$
/**
* Property name constant (value "field_editor_value")
* to signal a change in the value of this field editor.
*/
public static final String VALUE = "field_editor_value";//$NON-NLS-1$
/**
* Gap between label and control.
*/
protected static final int HORIZONTAL_GAP = 8;
/**
* The preference store, or null if none.
*/
private IPreferenceStore preferenceStore = null;
/**
* The name of the preference displayed in this field editor.
*/
private String preferenceName;
/**
* Indicates whether the default value is currently displayed,
* initially false.
*/
private boolean isDefaultPresented = false;
/**
* The label's text.
*/
private String labelText;
/**
* The label control.
*/
private Label label;
/**
* Listener, or null if none
*/
private IPropertyChangeListener propertyChangeListener;
/**
* The page containing this field editor
*/
private DialogPage page;
/**
* Creates a new field editor.
*/
protected FieldEditor() {
}
/**
* Creates a new field editor.
*
* @param name the name of the preference this field editor works on
* @param labelText the label text of the field editor
* @param parent the parent of the field editor's control
*/
protected FieldEditor(String name, String labelText, Composite parent) {
init(name, labelText);
createControl(parent);
}
/**
* Adjusts the horizontal span of this field editor's basic controls.
*
* Subclasses must implement this method to adjust the horizontal span
* of controls so they appear correct in the given number of columns.
*
*
* The number of columns will always be equal to or greater than the
* value returned by this editor's getNumberOfControls method.
*
* @param numColumns the number of columns
*/
protected abstract void adjustForNumColumns(int numColumns);
/**
* Applies a font.
*
* The default implementation of this framework method
* does nothing. Subclasses should override this method
* if they want to change the font of the SWT control to
* a value different than the standard dialog font.
*
*/
protected void applyFont() {
}
/**
* Checks if the given parent is the current parent of the
* supplied control; throws an (unchecked) exception if they
* are not correctly related.
*
* @param control the control
* @param parent the parent control
*/
protected void checkParent(Control control, Composite parent) {
Assert.isTrue(control.getParent() == parent, "Different parents");//$NON-NLS-1$
}
/**
* Clears the error message from the message line.
*/
protected void clearErrorMessage() {
if (page != null) {
page.setErrorMessage(null);
}
}
/**
* Clears the normal message from the message line.
*/
protected void clearMessage() {
if (page != null) {
page.setMessage(null);
}
}
/**
* Returns the number of pixels corresponding to the
* given number of horizontal dialog units.
*
* Clients may call this framework method, but should not override it.
*
*
* @param control the control being sized
* @param dlus the number of horizontal dialog units
* @return the number of pixels
*/
protected int convertHorizontalDLUsToPixels(Control control, int dlus) {
GC gc = new GC(control);
gc.setFont(control.getFont());
int averageWidth = gc.getFontMetrics().getAverageCharWidth();
gc.dispose();
double horizontalDialogUnitSize = averageWidth * 0.25;
return (int) Math.round(dlus * horizontalDialogUnitSize);
}
/**
* Returns the number of pixels corresponding to the
* given number of vertical dialog units.
*
* Clients may call this framework method, but should not override it.
*
*
* @param control the control being sized
* @param dlus the number of vertical dialog units
* @return the number of pixels
*/
protected int convertVerticalDLUsToPixels(Control control, int dlus) {
GC gc = new GC(control);
gc.setFont(control.getFont());
int height = gc.getFontMetrics().getHeight();
gc.dispose();
double verticalDialogUnitSize = height * 0.125;
return (int) Math.round(dlus * verticalDialogUnitSize);
}
/**
* Creates this field editor's main control containing all of its
* basic controls.
*
* @param parent the parent control
*/
protected void createControl(Composite parent) {
GridLayout layout = new GridLayout();
layout.numColumns = getNumberOfControls();
layout.marginWidth = 0;
layout.marginHeight = 0;
layout.horizontalSpacing = HORIZONTAL_GAP;
parent.setLayout(layout);
doFillIntoGrid(parent, layout.numColumns);
}
/**
* Disposes the SWT resources used by this field editor.
*/
public void dispose() {
// nothing to dispose
}
/**
* Fills this field editor's basic controls into the given parent.
*
* Subclasses must implement this method to create the controls
* for this field editor.
*
*
* Note this method may be called by the constructor, so it must not access
* fields on the receiver object because they will not be fully initialized.
*
*
* @param parent the composite used as a parent for the basic controls;
* the parent's layout must be a GridLayout
* @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.
*
* Subclasses must implement this method to properly initialize
* the field editor.
*
*/
protected abstract void doLoad();
/**
* Initializes this field editor with the default preference value from
* the preference store.
*
* Subclasses must implement this method to properly initialize
* the field editor.
*
*/
protected abstract void doLoadDefault();
/**
* Stores the preference value from this field editor into
* the preference store.
*
* Subclasses must implement this method to save the entered value
* into the preference store.
*
*/
protected abstract void doStore();
/**
* Fills this field editor's basic controls into the given parent.
*
* @param parent the composite used as a parent for the basic controls;
* the parent's layout must be a GridLayout
* @param numColumns the number of columns
*/
public void fillIntoGrid(Composite parent, int numColumns) {
Assert.isTrue(numColumns >= getNumberOfControls());
Assert.isTrue(parent.getLayout() instanceof GridLayout);
doFillIntoGrid(parent, numColumns);
}
/**
* Informs this field editor's listener, if it has one, about a change to
* one of this field editor's boolean-valued properties. Does nothing
* if the old and new values are the same.
*
* @param property the field editor property name,
* such as VALUE or IS_VALID
* @param oldValue the old value
* @param newValue the new value
*/
protected void fireStateChanged(String property, boolean oldValue,
boolean newValue) {
if (oldValue == newValue) {
return;
}
fireValueChanged(property, oldValue ? Boolean.TRUE : Boolean.FALSE, newValue ? Boolean.TRUE : Boolean.FALSE);
}
/**
* Informs this field editor's listener, if it has one, about a change to
* one of this field editor's properties.
*
* @param property the field editor property name,
* such as VALUE or IS_VALID
* @param oldValue the old value object, or null
* @param newValue the new value, or null
*/
protected void fireValueChanged(String property, Object oldValue,
Object newValue) {
if (propertyChangeListener == null) {
return;
}
propertyChangeListener.propertyChange(new PropertyChangeEvent(this,
property, oldValue, newValue));
}
/**
* Returns the symbolic font name used by this field editor.
*
* @return the symbolic font name
*/
public String getFieldEditorFontName() {
return JFaceResources.DIALOG_FONT;
}
/**
* Returns the label control.
*
* @return the label control, or null
* if no label control has been created
*/
protected Label getLabelControl() {
return label;
}
/**
* Returns this field editor's label component.
*
* The label is created if it does not already exist
*
*
* @param parent the parent
* @return the label control
*/
public Label getLabelControl(Composite parent) {
if (label == null) {
label = new Label(parent, SWT.LEFT);
label.setFont(parent.getFont());
String text = getLabelText();
if (text != null) {
label.setText(text);
}
label.addDisposeListener(event -> label = null);
} else {
checkParent(label, parent);
}
return label;
}
/**
* Returns this field editor's label text.
*
* @return the label text
*/
public String getLabelText() {
return labelText;
}
/**
* Returns the number of basic controls this field editor consists of.
*
* @return the number of controls
*/
public abstract int getNumberOfControls();
/**
* Returns the name of the preference this field editor operates on.
*
* @return the name of the preference
*/
public String getPreferenceName() {
return preferenceName;
}
/**
* Returns the preference page in which this field editor
* appears.
*
* @return the preference page, or null if none
* @deprecated use #getPage()
*/
@Deprecated
protected PreferencePage getPreferencePage() {
if(page != null && page instanceof PreferencePage) {
return (PreferencePage) page;
}
return null;
}
/**
* Return the DialogPage that the receiver is sending
* updates to.
*
* @return DialogPage or null if it
* has not been set.
*
* @since 3.1
*/
protected DialogPage getPage(){
return page;
}
/**
* Returns the preference store used by this field editor.
*
* @return the preference store, or null if none
* @see #setPreferenceStore
*/
public IPreferenceStore getPreferenceStore() {
return preferenceStore;
}
/**
* Initialize the field editor with the given preference name and label.
*
* @param name the name of the preference this field editor works on
* @param text the label text of the field editor
*/
protected void init(String name, String text) {
Assert.isNotNull(name);
Assert.isNotNull(text);
preferenceName = name;
this.labelText = text;
}
/**
* Returns whether this field editor contains a valid value.
*
* The default implementation of this framework method
* returns true. Subclasses wishing to perform
* validation should override both this method and
* refreshValidState.
*
*
* @return true if the field value is valid,
* and false if invalid
* @see #refreshValidState()
*/
public boolean isValid() {
return true;
}
/**
* Initializes this field editor with the preference value from
* the preference store.
*/
public void load() {
if (preferenceStore != null) {
isDefaultPresented = false;
doLoad();
refreshValidState();
}
}
/**
* Initializes this field editor with the default preference value
* from the preference store.
*/
public void loadDefault() {
if (preferenceStore != null) {
isDefaultPresented = true;
doLoadDefault();
refreshValidState();
}
}
/**
* Returns whether this field editor currently presents the
* default value for its preference.
*
* @return true if the default value is presented,
* and false otherwise
*/
public boolean presentsDefaultValue() {
return isDefaultPresented;
}
/**
* Refreshes this field editor's valid state after a value change
* and fires an IS_VALID property change event if
* warranted.
*
* The default implementation of this framework method does
* nothing. Subclasses wishing to perform validation should override
* both this method and isValid.
*
*
* @see #isValid
*/
protected void refreshValidState() {
}
/**
* Sets the focus to this field editor.
*
* The default implementation of this framework method
* does nothing. Subclasses may reimplement.
*
*/
public void setFocus() {
// do nothing;
}
/**
* Sets this field editor's label text.
* The label is typically presented to the left of the entry field.
*
* @param text the label text
*/
public void setLabelText(String text) {
Assert.isNotNull(text);
labelText = text;
if (label != null) {
label.setText(text);
}
}
/**
* Sets the name of the preference this field editor operates on.
*
* The ability to change this allows the same field editor object
* to be reused for different preferences.
*
*
* For example:
*
* ...
* editor.setPreferenceName("font");
* editor.load();
*
*
*
* @param name the name of the preference
*/
public void setPreferenceName(String name) {
preferenceName = name;
}
/**
* Sets the preference page in which this field editor
* appears.
*
* @param preferencePage the preference page, or null if none
* @deprecated use #setPage(DialogPage)
*/
@Deprecated
public void setPreferencePage(PreferencePage preferencePage) {
setPage(preferencePage);
}
/**
* Set the page to be the receiver.
* @param dialogPage
*
* @since 3.1
*/
public void setPage(DialogPage dialogPage) {
page = dialogPage;
}
/**
* Sets the preference store used by this field editor.
*
* @param store the preference store, or null if none
* @see #getPreferenceStore
*/
public void setPreferenceStore(IPreferenceStore store) {
preferenceStore = store;
}
/**
* Sets whether this field editor is presenting the default value.
*
* @param booleanValue true if the default value is being presented,
* and false otherwise
*/
protected void setPresentsDefaultValue(boolean booleanValue) {
isDefaultPresented = booleanValue;
}
/**
* Sets or removes the property change listener for this field editor.
*
* Note that field editors can support only a single listener.
*
*
* @param listener a property change listener, or null
* to remove
*/
public void setPropertyChangeListener(IPropertyChangeListener listener) {
propertyChangeListener = listener;
}
/**
* Shows the given error message in the page for this
* field editor if it has one.
*
* @param msg the error message
*/
protected void showErrorMessage(String msg) {
if (page != null) {
page.setErrorMessage(msg);
}
}
/**
* Shows the given message in the page for this
* field editor if it has one.
*
* @param msg the message
*/
protected void showMessage(String msg) {
if (page != null) {
page.setErrorMessage(msg);
}
}
/**
* Stores this field editor's value back into the preference store.
*/
public void store() {
if (preferenceStore == null) {
return;
}
if (isDefaultPresented) {
preferenceStore.setToDefault(preferenceName);
} else {
doStore();
}
}
/**
* Set the GridData on button to be one that is spaced for the
* current font.
* @param button the button the data is being set on.
*/
protected void setButtonLayoutData(Button button) {
GridData data = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
// Compute and store a font metric
GC gc = new GC(button);
gc.setFont(button.getFont());
FontMetrics fontMetrics = gc.getFontMetrics();
gc.dispose();
int widthHint = org.eclipse.jface.dialogs.Dialog
.convertVerticalDLUsToPixels(fontMetrics,
IDialogConstants.BUTTON_WIDTH);
data.widthHint = Math.max(widthHint, button.computeSize(SWT.DEFAULT,
SWT.DEFAULT, true).x);
button.setLayoutData(data);
}
/**
* Set whether or not the controls in the field editor
* are enabled.
* @param enabled The enabled state.
* @param parent The parent of the controls in the group.
* Used to create the controls if required.
*/
public void setEnabled(boolean enabled, Composite parent) {
getLabelControl(parent).setEnabled(enabled);
}
}