/*******************************************************************************
 * Copyright (c) 2000, 2019 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.preference;

import org.eclipse.core.runtime.Assert;
import org.eclipse.jface.dialogs.DialogPage;
import org.eclipse.jface.dialogs.IDialogConstants;
import org.eclipse.jface.resource.JFaceResources;
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.
 * <p>
 * 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.
 * </p>
 * <p>
 * Field editors should be used in conjunction with a field editor preference
 * page (<code>FieldEditorPreferencePage</code>) which coordinates everything
 * and provides the message line which display messages emanating from the
 * editor.
 * </p>
 * <p>
 * This package contains ready-to-use field editors for various types of
 * preferences:
 * </p>
 * <ul>
 * <li><code>BooleanFieldEditor</code> - booleans</li>
 * <li><code>IntegerFieldEditor</code> - integers</li>
 * <li><code>StringFieldEditor</code> - text strings</li>
 * <li><code>RadioGroupFieldEditor</code> - enumerations</li>
 * <li><code>ColorFieldEditor</code> - RGB colors</li>
 * <li><code>FontFieldEditor</code> - fonts</li>
 * <li><code>DirectoryFieldEditor</code> - directories</li>
 * <li><code>FileFieldEditor</code> - files</li>
 * <li><code>PathEditor</code> - paths</li>
 * </ul>
 */
public abstract class FieldEditor {

	/**
	 * Property name constant (value <code>"field_editor_is_valid"</code>)
	 * 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 <code>"field_editor_value"</code>)
	 * 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 <code>null</code> 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 <code>false</code>.
	 */
	private boolean isDefaultPresented = false;

	/**
	 * The label's text.
	 */
	private String labelText;

	/**
	 * The label control.
	 */
	private Label label;

	/**
	 * Listener, or <code>null</code> 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.
	 * <p>
	 * Subclasses must implement this method to adjust the horizontal span
	 * of controls so they appear correct in the given number of columns.
	 * </p>
	 * <p>
	 * The number of columns will always be equal to or greater than the
	 * value returned by this editor's <code>getNumberOfControls</code> method.
	 *
	 * @param numColumns the number of columns
	 */
	protected abstract void adjustForNumColumns(int numColumns);

	/**
	 * Applies a font.
	 * <p>
	 * 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.
	 * </p>
	 */
	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.
	 * <p>
	 * Clients may call this framework method, but should not override it.
	 * </p>
	 *
	 * @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 = (int) gc.getFontMetrics().getAverageCharacterWidth();
		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.
	 * <p>
	 * Clients may call this framework method, but should not override it.
	 * </p>
	 *
	 * @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.
	 * <p>
	 * Subclasses must implement this method to create the controls
	 * for this field editor.
	 * </p>
	 * <p>
	 * 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.
	 * </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();

	/**
	 * Stores the preference value from this field editor into
	 * the preference store.
	 * <p>
	 * Subclasses must implement this method to save the entered value
	 * into the preference store.
	 * </p>
	 */
	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 <code>GridLayout</code>
	 * @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 <code>VALUE</code> or <code>IS_VALID</code>
	 * @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 <code>VALUE</code> or <code>IS_VALID</code>
	 * @param oldValue the old value object, or <code>null</code>
	 * @param newValue the new value, or <code>null</code>
	 */
	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 <code>null</code>
	 *  if no label control has been created
	 */
	protected Label getLabelControl() {
		return label;
	}

	/**
	 * Returns this field editor's label component.
	 * <p>
	 * The label is created if it does not already exist
	 * </p>
	 *
	 * @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 <code>null</code> 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 <code>null</code> 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 <code>null</code> 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.
	 * <p>
	 * The default implementation of this framework method
	 * returns <code>true</code>. Subclasses wishing to perform
	 * validation should override both this method and
	 * <code>refreshValidState</code>.
	 * </p>
	 *
	 * @return <code>true</code> if the field value is valid,
	 *   and <code>false</code> 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 (getPreferenceStore() != null) {
			isDefaultPresented = false;
			doLoad();
			refreshValidState();
		}
	}

	/**
	 * Initializes this field editor with the default preference value
	 * from the preference store.
	 */
	public void loadDefault() {
		if (getPreferenceStore() != null) {
			isDefaultPresented = true;
			doLoadDefault();
			refreshValidState();
		}
	}

	/**
	 * Returns whether this field editor currently presents the
	 * default value for its preference.
	 *
	 * @return <code>true</code> if the default value is presented,
	 *   and <code>false</code> otherwise
	 */
	public boolean presentsDefaultValue() {
		return isDefaultPresented;
	}

	/**
	 * Refreshes this field editor's valid state after a value change
	 * and fires an <code>IS_VALID</code> property change event if
	 * warranted.
	 * <p>
	 * The default implementation of this framework method does
	 * nothing. Subclasses wishing to perform validation should override
	 * both this method and <code>isValid</code>.
	 * </p>
	 *
	 * @see #isValid
	 */
	protected void refreshValidState() {
	}

	/**
	 * Sets the focus to this field editor.
	 * <p>
	 * The default implementation of this framework method
	 * does nothing. Subclasses may reimplement.
	 * </p>
	 */
	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.
	 * <p>
	 * The ability to change this allows the same field editor object to be reused
	 * for different preferences.
	 * </p>
	 * <p>
	 * For example:
	 * </p>
	 *
	 * <pre>
	 * 	...
	 *  editor.setPreferenceName("font");
	 * 	editor.load();
	 * </pre>
	 *
	 * @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 <code>null</code> if none
	 * @deprecated use #setPage(DialogPage)
	 */
	@Deprecated
	public void setPreferencePage(PreferencePage preferencePage) {
		setPage(preferencePage);
	}


	/**
	 * Set the page to be the receiver.
	 *
	 * @param dialogPage the new receiver
	 *
	 * @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 <code>null</code> if none
	 * @see #getPreferenceStore
	 */
	public void setPreferenceStore(IPreferenceStore store) {
		preferenceStore = store;
	}

	/**
	 * Sets whether this field editor is presenting the default value.
	 *
	 * @param booleanValue <code>true</code> if the default value is being presented,
	 *  and <code>false</code> otherwise
	 */
	protected void setPresentsDefaultValue(boolean booleanValue) {
		isDefaultPresented = booleanValue;
	}

	/**
	 * Sets or removes the property change listener for this field editor.
	 * <p>
	 * Note that field editors can support only a single listener.
	 * </p>
	 *
	 * @param listener a property change listener, or <code>null</code>
	 *  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() {
		IPreferenceStore store = getPreferenceStore();
		if (store == null) {
			return;
		}

		if (isDefaultPresented) {
			store.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);
	}

}
