001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.dialogs;
011:
012: import org.eclipse.jface.resource.ImageDescriptor;
013: import org.eclipse.jface.resource.JFaceResources;
014: import org.eclipse.swt.SWT;
015: import org.eclipse.swt.graphics.Font;
016: import org.eclipse.swt.graphics.FontMetrics;
017: import org.eclipse.swt.graphics.GC;
018: import org.eclipse.swt.graphics.Image;
019: import org.eclipse.swt.graphics.Point;
020: import org.eclipse.swt.layout.GridData;
021: import org.eclipse.swt.widgets.Button;
022: import org.eclipse.swt.widgets.Control;
023: import org.eclipse.swt.widgets.Shell;
024:
025: /**
026: * Abstract base implementation of a dialog page. All dialog pages are
027: * subclasses of this one.
028: */
029: public abstract class DialogPage implements IDialogPage,
030: IMessageProvider {
031: /**
032: * The control for this dialog page.
033: */
034: private Control control;
035:
036: /**
037: * Optional title; <code>null</code> if none.
038: *
039: * @see #setTitle
040: */
041: private String title = null;
042:
043: /**
044: * Optional description; <code>null</code> if none.
045: *
046: * @see #setDescription
047: */
048: private String description = null;
049:
050: /**
051: * Cached image; <code>null</code> if none.
052: *
053: * @see #setImageDescriptor(ImageDescriptor)
054: */
055: private Image image = null;
056:
057: /**
058: * Optional image; <code>null</code> if none.
059: *
060: * @see #setImageDescriptor(ImageDescriptor)
061: */
062: private ImageDescriptor imageDescriptor = null;
063:
064: /**
065: * The current message; <code>null</code> if none.
066: */
067: private String message = null;
068:
069: /**
070: * The current message type; default value <code>NONE</code>.
071: */
072: private int messageType = NONE;
073:
074: /**
075: * The current error message; <code>null</code> if none.
076: */
077: private String errorMessage = null;
078:
079: /**
080: * Font metrics to use for determining pixel sizes.
081: */
082: private FontMetrics fontMetrics;
083:
084: /**
085: * Creates a new empty dialog page.
086: */
087: protected DialogPage() {
088: //No initial behaviour
089: }
090:
091: /**
092: * Creates a new dialog page with the given title.
093: *
094: * @param title
095: * the title of this dialog page, or <code>null</code> if none
096: */
097: protected DialogPage(String title) {
098: this .title = title;
099: }
100:
101: /**
102: * Creates a new dialog page with the given title and image.
103: *
104: * @param title
105: * the title of this dialog page, or <code>null</code> if none
106: * @param image
107: * the image for this dialog page, or <code>null</code> if none
108: */
109: protected DialogPage(String title, ImageDescriptor image) {
110: this (title);
111: imageDescriptor = image;
112: }
113:
114: /**
115: * Returns the number of pixels corresponding to the height of the given
116: * number of characters.
117: * <p>
118: * This method may only be called after <code>initializeDialogUnits</code>
119: * has been called.
120: * </p>
121: * <p>
122: * Clients may call this framework method, but should not override it.
123: * </p>
124: *
125: * @param chars
126: * the number of characters
127: * @return the number of pixels
128: */
129: protected int convertHeightInCharsToPixels(int chars) {
130: // test for failure to initialize for backward compatibility
131: if (fontMetrics == null) {
132: return 0;
133: }
134: return Dialog.convertHeightInCharsToPixels(fontMetrics, chars);
135: }
136:
137: /**
138: * Returns the number of pixels corresponding to the given number of
139: * horizontal dialog units.
140: * <p>
141: * This method may only be called after <code>initializeDialogUnits</code>
142: * has been called.
143: * </p>
144: * <p>
145: * Clients may call this framework method, but should not override it.
146: * </p>
147: *
148: * @param dlus
149: * the number of horizontal dialog units
150: * @return the number of pixels
151: */
152: protected int convertHorizontalDLUsToPixels(int dlus) {
153: // test for failure to initialize for backward compatibility
154: if (fontMetrics == null) {
155: return 0;
156: }
157: return Dialog.convertHorizontalDLUsToPixels(fontMetrics, dlus);
158: }
159:
160: /**
161: * Returns the number of pixels corresponding to the given number of
162: * vertical dialog units.
163: * <p>
164: * This method may only be called after <code>initializeDialogUnits</code>
165: * has been called.
166: * </p>
167: * <p>
168: * Clients may call this framework method, but should not override it.
169: * </p>
170: *
171: * @param dlus
172: * the number of vertical dialog units
173: * @return the number of pixels
174: */
175: protected int convertVerticalDLUsToPixels(int dlus) {
176: // test for failure to initialize for backward compatibility
177: if (fontMetrics == null) {
178: return 0;
179: }
180: return Dialog.convertVerticalDLUsToPixels(fontMetrics, dlus);
181: }
182:
183: /**
184: * Returns the number of pixels corresponding to the width of the given
185: * number of characters.
186: * <p>
187: * This method may only be called after <code>initializeDialogUnits</code>
188: * has been called.
189: * </p>
190: * <p>
191: * Clients may call this framework method, but should not override it.
192: * </p>
193: *
194: * @param chars
195: * the number of characters
196: * @return the number of pixels
197: */
198: protected int convertWidthInCharsToPixels(int chars) {
199: // test for failure to initialize for backward compatibility
200: if (fontMetrics == null) {
201: return 0;
202: }
203: return Dialog.convertWidthInCharsToPixels(fontMetrics, chars);
204: }
205:
206: /**
207: * The <code>DialogPage</code> implementation of an
208: * <code>IDialogPage</code> method does nothing. Subclasses may extend.
209: */
210: public void dispose() {
211: // deallocate SWT resources
212: if (image != null) {
213: image.dispose();
214: image = null;
215: }
216: }
217:
218: /**
219: * Returns the top level control for this dialog page.
220: *
221: * @return the top level control
222: */
223: public Control getControl() {
224: return control;
225: }
226:
227: /*
228: * (non-Javadoc) Method declared on IDialogPage.
229: */
230: public String getDescription() {
231: return description;
232: }
233:
234: /**
235: * Returns the symbolic font name used by dialog pages.
236: *
237: * @return the symbolic font name
238: */
239: protected String getDialogFontName() {
240: return JFaceResources.DIALOG_FONT;
241: }
242:
243: /*
244: * (non-Javadoc) Method declared on IDialogPage.
245: */
246: public String getErrorMessage() {
247: return errorMessage;
248: }
249:
250: /**
251: * Returns the default font to use for this dialog page.
252: *
253: * @return the font
254: */
255: protected Font getFont() {
256: return JFaceResources.getFontRegistry()
257: .get(getDialogFontName());
258: }
259:
260: /*
261: * (non-Javadoc) Method declared on IDialogPage.
262: */
263: public Image getImage() {
264: if (image == null) {
265: if (imageDescriptor != null) {
266: image = imageDescriptor.createImage();
267: }
268: }
269: return image;
270: }
271:
272: /*
273: * (non-Javadoc) Method declared on IDialogPage.
274: */
275: public String getMessage() {
276: return message;
277: }
278:
279: /*
280: * (non-Javadoc) Method declared on IMessageProvider.
281: */
282: public int getMessageType() {
283: return messageType;
284: }
285:
286: /**
287: * Returns this dialog page's shell. Convenience method for
288: * <code>getControl().getShell()</code>. This method may only be called
289: * after the page's control has been created.
290: *
291: * @return the shell
292: */
293: public Shell getShell() {
294: return getControl().getShell();
295: }
296:
297: /*
298: * (non-Javadoc) Method declared on IDialogPage.
299: */
300: public String getTitle() {
301: return title;
302: }
303:
304: /**
305: * Returns the tool tip text for the widget with the given id.
306: * <p>
307: * The default implementation of this framework method does nothing and
308: * returns <code>null</code>. Subclasses may override.
309: * </p>
310: *
311: * @param widgetId
312: * the id of the widget for which hover help is requested
313: * @return the tool tip text, or <code>null</code> if none
314: * @deprecated
315: */
316: protected final String getToolTipText(int widgetId) {
317: // return nothing by default
318: return null;
319: }
320:
321: /**
322: * Initializes the computation of horizontal and vertical dialog units based
323: * on the size of current font.
324: * <p>
325: * This method must be called before any of the dialog unit based conversion
326: * methods are called.
327: * </p>
328: *
329: * @param testControl
330: * a control from which to obtain the current font
331: */
332: protected void initializeDialogUnits(Control testControl) {
333: // Compute and store a font metric
334: GC gc = new GC(testControl);
335: gc.setFont(JFaceResources.getDialogFont());
336: fontMetrics = gc.getFontMetrics();
337: gc.dispose();
338: }
339:
340: /**
341: * Sets the <code>GridData</code> on the specified button to be one that
342: * is spaced for the current dialog page units. The method
343: * <code>initializeDialogUnits</code> must be called once before calling
344: * this method for the first time.
345: *
346: * @param button
347: * the button to set the <code>GridData</code>
348: * @return the <code>GridData</code> set on the specified button
349: */
350: protected GridData setButtonLayoutData(Button button) {
351: GridData data = new GridData(GridData.HORIZONTAL_ALIGN_FILL);
352: int widthHint = convertHorizontalDLUsToPixels(IDialogConstants.BUTTON_WIDTH);
353: Point minSize = button.computeSize(SWT.DEFAULT, SWT.DEFAULT,
354: true);
355: data.widthHint = Math.max(widthHint, minSize.x);
356: button.setLayoutData(data);
357: return data;
358: }
359:
360: /**
361: * Tests whether this page's UI content has already been created.
362: *
363: * @return <code>true</code> if the control has been created, and
364: * <code>false</code> if not
365: */
366: protected boolean isControlCreated() {
367: return control != null;
368: }
369:
370: /**
371: * This default implementation of an <code>IDialogPage</code> method does
372: * nothing. Subclasses should override to take some action in response to a
373: * help request.
374: */
375: public void performHelp() {
376: //No default help
377: }
378:
379: /**
380: * Set the control for the receiver.
381: * @param newControl
382: */
383: protected void setControl(Control newControl) {
384: control = newControl;
385: }
386:
387: /*
388: * (non-Javadoc) Method declared on IDialogPage.
389: */
390: public void setDescription(String description) {
391: this .description = description;
392: }
393:
394: /**
395: * Sets or clears the error message for this page.
396: *
397: * @param newMessage
398: * the message, or <code>null</code> to clear the error message
399: */
400: public void setErrorMessage(String newMessage) {
401: errorMessage = newMessage;
402: }
403:
404: /*
405: * (non-Javadoc) Method declared on IDialogPage.
406: */
407: public void setImageDescriptor(ImageDescriptor desc) {
408: imageDescriptor = desc;
409: if (image != null) {
410: image.dispose();
411: image = null;
412: }
413: }
414:
415: /**
416: * Sets or clears the message for this page.
417: * <p>
418: * This is a shortcut for <code>setMessage(newMesasge, NONE)</code>
419: * </p>
420: *
421: * @param newMessage
422: * the message, or <code>null</code> to clear the message
423: */
424: public void setMessage(String newMessage) {
425: setMessage(newMessage, NONE);
426: }
427:
428: /**
429: * Sets the message for this page with an indication of what type of message
430: * it is.
431: * <p>
432: * The valid message types are one of <code>NONE</code>,
433: * <code>INFORMATION</code>,<code>WARNING</code>, or
434: * <code>ERROR</code>.
435: * </p>
436: * <p>
437: * Note that for backward compatibility, a message of type
438: * <code>ERROR</code> is different than an error message (set using
439: * <code>setErrorMessage</code>). An error message overrides the current
440: * message until the error message is cleared. This method replaces the
441: * current message and does not affect the error message.
442: * </p>
443: *
444: * @param newMessage
445: * the message, or <code>null</code> to clear the message
446: * @param newType
447: * the message type
448: * @since 2.0
449: */
450: public void setMessage(String newMessage, int newType) {
451: message = newMessage;
452: messageType = newType;
453: }
454:
455: /**
456: * The <code>DialogPage</code> implementation of this
457: * <code>IDialogPage</code> method remembers the title in an internal
458: * state variable. Subclasses may extend.
459: */
460: public void setTitle(String title) {
461: this .title = title;
462: }
463:
464: /**
465: * The <code>DialogPage</code> implementation of this
466: * <code>IDialogPage</code> method sets the control to the given
467: * visibility state. Subclasses may extend.
468: */
469: public void setVisible(boolean visible) {
470: control.setVisible(visible);
471: }
472: }
|