bundles/org.eclipse.jface/src/org/eclipse/jface/dialogs/DialogPage.java

/*******************************************************************************
 * Copyright (c) 2000, 2003 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials 
 * are made available under the terms of the Common Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/cpl-v10.html
 * 
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.dialogs;

import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.*;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.widgets.*;

/**
 * Abstract base implementation of a dialog page.
 * All dialog pages are subclasses of this one.
 */
public abstract class DialogPage implements IDialogPage, IMessageProvider {
	/**
	 * The control for this dialog page.
	 */
	private Control control;
	/**
	 * Optional title; <code>null</code> if none.
	 *
	 * @see #setTitle
	 */
	private String title = null;
	/**
	 * Optional description; <code>null</code> if none.
	 *
	 * @see #setDescription
	 */
	private String description = null;
	/**
	 * Cached image; <code>null</code> if none.
	 *
	 * @see #setImageDescription
	 */
	private Image image = null;
	/**
	 * Optional image; <code>null</code> if none.
	 *
	 * @see #setImageDescription
	 */
	private ImageDescriptor imageDescriptor = null;
	/**
	 * The current message; <code>null</code> if none.
	 */
	private String message = null;
	/**
	 * The current message type; default value <code>NONE</code>.
	 */
	private int messageType = NONE;
	/**
	 * The current error message; <code>null</code> if none.
	 */
	private String errorMessage = null;

	/**
	 * Font metrics to use for determining pixel sizes.
	 */
	private FontMetrics fontMetrics;

/**
 * Creates a new empty dialog page.
 */
protected DialogPage() {
}
/**
 * Creates a new dialog page with the given title.
 *
 * @param title the title of this dialog page, 
 *  or <code>null</code> if none
 */
protected DialogPage(String title) {
	this.title = title;
}
/**
 * Creates a new dialog page with the given title and image.
 *
 * @param title the title of this dialog page, 
 *  or <code>null</code> if none
 * @param image the image for this dialog page, 
 *  or <code>null</code> if none
 */
protected DialogPage(String title, ImageDescriptor image) {
	this(title);
	imageDescriptor = image;
}
/**
 * Returns the number of pixels corresponding to the
 * height of the given number of characters.
 * <p>
 * This method may only be called after <code>initializeDialogUnits</code>
 * has been called.
 * </p>
 * <p>
 * Clients may call this framework method, but should not override it.
 * </p>
 *
 * @param chars the number of characters
 * @return the number of pixels
 */
protected int convertHeightInCharsToPixels(int chars) {
	// test for failure to initialize for backward compatibility
	if (fontMetrics == null)
		return 0;
	return Dialog.convertHeightInCharsToPixels(fontMetrics, chars);
}
/**
 * Returns the number of pixels corresponding to the
 * given number of horizontal dialog units.
 * <p>
 * This method may only be called after <code>initializeDialogUnits</code>
 * has been called.
 * </p>
 * <p>
 * Clients may call this framework method, but should not override it.
 * </p>
 *
 * @param dlus the number of horizontal dialog units
 * @return the number of pixels
 */
protected int convertHorizontalDLUsToPixels(int dlus) {
	// test for failure to initialize for backward compatibility
	if (fontMetrics == null)
		return 0;
	return Dialog.convertHorizontalDLUsToPixels(fontMetrics, dlus);
}
/**
 * Returns the number of pixels corresponding to the
 * given number of vertical dialog units.
 * <p>
 * This method may only be called after <code>initializeDialogUnits</code>
 * has been called.
 * </p>
 * <p>
 * Clients may call this framework method, but should not override it.
 * </p>
 *
 * @param dlus the number of vertical dialog units
 * @return the number of pixels
 */
protected int convertVerticalDLUsToPixels(int dlus) {
	// test for failure to initialize for backward compatibility
	if (fontMetrics == null)
		return 0;
	return Dialog.convertVerticalDLUsToPixels(fontMetrics, dlus);
}
/**
 * Returns the number of pixels corresponding to the
 * width of the given number of characters.
 * <p>
 * This method may only be called after <code>initializeDialogUnits</code>
 * has been called.
 * </p>
 * <p>
 * Clients may call this framework method, but should not override it.
 * </p>
 *
 * @param chars the number of characters
 * @return the number of pixels
 */
protected int convertWidthInCharsToPixels(int chars) {
	// test for failure to initialize for backward compatibility
	if (fontMetrics == null)
		return 0;
	return Dialog.convertWidthInCharsToPixels(fontMetrics, chars);
}
/**	
 * The <code>DialogPage</code> implementation of an <code>IDialogPage</code>
 * method does nothing. Subclasses may extend.
 */
public void dispose() {
	// deallocate SWT resources
	if (image != null) {
		image.dispose();
		image = null;
	}		
}
/**
 * Returns the top level control for this dialog page.
 *
 * @return the top level control
 */
public Control getControl() {
	return control;	
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public String getDescription() {
	return description;
}
/**
 * Returns the symbolic font name used by dialog pages.
 *
 * @return the symbolic font name
 */
protected String getDialogFontName() {
	return JFaceResources.DIALOG_FONT;
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public String getErrorMessage() {
	return errorMessage;
}
/**
 * Returns the default font to use for this dialog page.
 *
 * @return the font
 */
protected Font getFont() {
	return JFaceResources.getFontRegistry().get(getDialogFontName());
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public Image getImage() {
	if (image == null) {
		if (imageDescriptor != null) {
			image = imageDescriptor.createImage();
		}
	}
	return image;
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public String getMessage() {
	return message;
}
/* (non-Javadoc)
 * Method declared on IMessageProvider.
 */
public int getMessageType() {
	return messageType;
}
/**
 * Returns this dialog page's shell.
 * Convenience method for <code>getControl().getShell()</code>.
 * This method may only be called after the page's control
 * has been created.
 *
 * @return the shell 
 */
public Shell getShell() {
	return getControl().getShell();
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public String getTitle() {
	return title;
}
/**
 * Returns the tool tip text for the widget with the given id.
 * <p>
 * The default implementation of this framework method
 * does nothing and returns <code>null</code>. 
 * Subclasses may override.
 * </p>
 *
 * @param widgetID the id of the widget for which  
 *    hover help is requested
 * @return the tool tip text, or <code>null</code> if none
 * @deprecated will be removed
 */
protected final String getToolTipText(int widgetId) {
	// return nothing by default
	return null;
}
/**
 * Initializes the computation of horizontal and vertical dialog units
 * based on the size of current font.
 * <p>
 * This method must be called before any of the dialog unit based
 * conversion methods are called.
 * </p>
 *
 * @param control a control from which to obtain the current font
 */
protected void initializeDialogUnits(Control testControl) {
	// Compute and store a font metric
	GC gc = new GC(testControl);
	gc.setFont(JFaceResources.getDialogFont());
	fontMetrics = gc.getFontMetrics();
	gc.dispose();
}

/**
 * Sets the <code>GridData</code> on the specified button to
 * be one that is spaced for the current dialog page units. The
 * method <code>initializeDialogUnits</code> must be called once
 * before calling this method for the first time.
 * 
 * @param button the button to set the <code>GridData</code>
 * @return the <code>GridData</code> set on the specified button
 */
protected GridData setButtonLayoutData(Button button) {
	GridData data = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
	data.heightHint = convertVerticalDLUsToPixels(IDialogConstants.BUTTON_HEIGHT);
	int widthHint = convertHorizontalDLUsToPixels(IDialogConstants.BUTTON_WIDTH);
	data.widthHint = Math.max(widthHint, button.computeSize(SWT.DEFAULT, SWT.DEFAULT, true).x);
	button.setLayoutData(data);
	return data;
}

/**
 * Tests whether this page's UI content has already been created.
 *
 * @return <code>true</code> if the control has been created,
 * and <code>false</code> if not
 */
protected boolean isControlCreated() {
	return control != null;
}
/**	
 * This default implementation of an <code>IDialogPage</code>
 * method does nothing. Subclasses should override to take some
 * action in response to a help request.
 */
public void performHelp() {
}
/* (non-Javadoc)
 * Set the control for this page.
 */
protected void setControl(Control newControl) {
	control = newControl;
}
	/* (non-Javadoc)
	 * Method declared on IDialogPage.
	 */
	public void setDescription(String description) {
		this.description= description;
	}
/**
 * Sets or clears the error message for this page.
 *
 * @param newMessage the message, or <code>null</code> to clear
 *   the error message
 */
public void setErrorMessage(String newMessage) {
	errorMessage = newMessage;
}
/* (non-Javadoc)
 * Method declared on IDialogPage.
 */
public void setImageDescriptor(ImageDescriptor desc) {
	imageDescriptor = desc;
	if (image != null) {
		image.dispose();
		image = null;
	}
}
/**
 * Sets or clears the message for this page.
 * <p>
 * This is a shortcut for <code>setMessage(newMesasge, NONE)</code>
 * </p>
 * @param newMessage the message, or <code>null</code> to clear
 *   the message
 */
public void setMessage(String newMessage) {
	setMessage(newMessage, NONE);
}
/**
 * Sets the message for this page with an indication of what type
 * of message it is.
 * <p>
 * The valid message types are one of <code>NONE</code>, 
 * <code>INFORMATION</code>, <code>WARNING</code>, or <code>ERROR</code>.
 * </p>
 * <p>
 * Note that for backward compatibility, a message of type <code>ERROR</code> 
 * is different than an error message (set using <code>setErrorMessage</code>). 
 * An error message overrides the current message until the error message is 
 * cleared. This method replaces the current message and does not affect the 
 * error message.
 * </p>
 *
 * @param newMessage the message, or <code>null</code> to clear
 *   the message
 * @param newType the message type
 * @since 2.0
 */
public void setMessage(String newMessage, int newType) {
	message = newMessage;
	messageType = newType;
}
/**
 * The <code>DialogPage</code> implementation of this <code>IDialogPage</code>
 * method remembers the title in an internal state variable.
 * Subclasses may extend.
 */
public void setTitle(String title) {
	this.title = title;
}
/**
 * The <code>DialogPage</code> implementation of this <code>IDialogPage</code>
 * method sets the control to the given visibility state.
 * Subclasses may extend.
 */
public void setVisible(boolean visible) {
	control.setVisible(visible);
}
}