/*******************************************************************************
* 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.dialogs;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.resource.JFaceResources;
import org.eclipse.swt.SWT;
import org.eclipse.swt.graphics.Font;
import org.eclipse.swt.graphics.FontMetrics;
import org.eclipse.swt.graphics.GC;
import org.eclipse.swt.graphics.Image;
import org.eclipse.swt.graphics.Point;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.widgets.Button;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Shell;
/**
* 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 #setImageDescriptor(ImageDescriptor)
*/
private Image image = null;
/**
* Optional image; <code>null</code> if none.
*
* @see #setImageDescriptor(ImageDescriptor)
*/
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() {
//No initial behaviour
}
/**
* 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 this
* <code>IDialogPage</code> method disposes of the page
* image if it has one.
* Subclasses may extend.
*/
@Override
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
*/
@Override
public Control getControl() {
return control;
}
@Override
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;
}
@Override
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());
}
@Override
public Image getImage() {
if (image == null) {
if (imageDescriptor != null) {
image = imageDescriptor.createImage();
}
}
return image;
}
@Override
public String getMessage() {
return message;
}
@Override
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();
}
@Override
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
*/
@Deprecated
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 testControl
* 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);
int widthHint = convertHorizontalDLUsToPixels(IDialogConstants.BUTTON_WIDTH);
Point minSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT, true);
data.widthHint = Math.max(widthHint, minSize.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.
*/
@Override
public void performHelp() {
//No default help
}
/**
* Set the control for the receiver.
* @param newControl
*/
protected void setControl(Control newControl) {
control = newControl;
}
@Override
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;
}
@Override
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.
*/
@Override
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.
*/
@Override
public void setVisible(boolean visible) {
control.setVisible(visible);
}
}