org.eclipse.swt.widgets.Dialog Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of gef-gwt
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2009, 2012 IBM Corporation, Gerhardt Informatics Kft. 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
 *     Gerhardt Informatics Kft. - GEFGWT port
 *******************************************************************************/
package org.eclipse.swt.widgets;

import org.eclipse.swt.SWT;
import org.eclipse.swt.SWTException;

/**
 * This class is the abstract superclass of the classes that represent the built
 * in platform dialogs. A Dialog typically contains other widgets
 * that are not accessible. A Dialog is not a Widget.
 * 
 * This class can also be used as the abstract superclass for user-designed
 * dialogs. Such dialogs usually consist of a Shell with child widgets. The
 * basic template for a user-defined dialog typically looks something like this:
 * 
 * 
 * 
 * public class MyDialog extends Dialog {
 * Object result;
 * 	
 * public MyDialog (Shell parent, int style) {
 * 	super (parent, style);
 * }
 * public MyDialog (Shell parent) {
 * 	this (parent, 0); // your default style bits go here (not the Shell's style bits)
 * }
 * public Object open () {
 * 	Shell parent = getParent();
 * 	Shell shell = new Shell(parent, SWT.DIALOG_TRIM | SWT.APPLICATION_MODAL);
 * 	shell.setText(getText());
 * 	// Your code goes here (widget creation, set result, etc).
 * 	shell.open();
 * 	Display display = parent.getDisplay();
 * 	while (!shell.isDisposed()) {
 * 		if (!display.readAndDispatch()) display.sleep();
 * 	}
 * 	return result;
 * }
 * }
 * 

 * 
 * 
 * 
 * Note: The modality styles supported by this class are treated as
 * HINTs, because not all are supported by every subclass on every
 * platform. If a modality style is not supported, it is "upgraded" to a more
 * restrictive modality style that is supported. For example, if
 * PRIMARY_MODAL is not supported by a particular dialog, it would
 * be upgraded to APPLICATION_MODAL. In addition, as is the case
 * for shells, the window manager for the desktop on which the instance is
 * visible has ultimate control over the appearance and behavior of the
 * instance, including its modality.
 * 

 * Styles:
 * APPLICATION_MODAL, PRIMARY_MODAL, SYSTEM_MODAL, SHEET
 * Events:
 * (none)
 * 
 * 
 * Note: Only one of the styles APPLICATION_MODAL, PRIMARY_MODAL, and
 * SYSTEM_MODAL may be specified.
 * 
 * 
 * @see Shell
 * @see SWT Example:
 *      ControlExample
 * @see Sample code and further
 *      information
 */

public abstract class Dialog {
	int style;
	Shell parent;
	String title;

	/**
	 * Constructs a new instance of this class given only its parent.
	 * 
	 * @param parent
	 *            a shell which will be the parent of the new instance
	 * 
	 * @exception IllegalArgumentException
	 *                
	 *                ERROR_NULL_ARGUMENT - if the parent is null
	 *                
	 * @exception SWTException
	 *                
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the parent
	 *                
	 */
	public Dialog(Shell parent) {
		this(parent, SWT.PRIMARY_MODAL);
	}

	/**
	 * Constructs a new instance of this class given its parent and a style
	 * value describing its behavior and appearance.
	 * 
	 * The style value is either one of the style constants defined in class
	 * SWT which is applicable to instances of this class, or must
	 * be built by bitwise OR'ing together (that is, using the
	 * int "|" operator) two or more of those SWT
	 * style constants. The class description lists the style constants that are
	 * applicable to the class. Style bits are also inherited from superclasses.
	 * 
	 * @param parent
	 *            a shell which will be the parent of the new instance
	 * @param style
	 *            the style of dialog to construct
	 * 
	 * @exception IllegalArgumentException
	 *                

	 *                ERROR_NULL_ARGUMENT - if the parent is null
	 *                
	 * @exception SWTException
	 *                
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the parent
	 *                
	 * 
	 * @see SWT#PRIMARY_MODAL
	 * @see SWT#APPLICATION_MODAL
	 * @see SWT#SYSTEM_MODAL
	 */
	public Dialog(Shell parent, int style) {
		checkParent(parent);
		this.parent = parent;
		this.style = style;
		title = "";
	}

	/**
	 * Checks that this class can be subclassed.
	 * 
	 * IMPORTANT: See the comment in Widget.checkSubclass().
	 * 
	 * 
	 * @exception SWTException
	 *                
	 *                ERROR_INVALID_SUBCLASS - if this class is not an
	 *                allowed subclass
	 *                
	 * 
	 * @see Widget#checkSubclass
	 */
	protected void checkSubclass() {
		if (!Display.isValidClass(getClass())) {
			error(SWT.ERROR_INVALID_SUBCLASS);
		}
	}

	/**
	 * Throws an exception if the specified widget can not be used as a parent
	 * for the receiver.
	 * 
	 * @exception IllegalArgumentException
	 *                
	 *                ERROR_NULL_ARGUMENT - if the parent is null
	 *                ERROR_INVALID_ARGUMENT - if the parent is disposed
	 *                
	 * @exception SWTException
	 *                
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the parent
	 *                
	 */
	void checkParent(Shell parent) {
		if (parent == null)
			error(SWT.ERROR_NULL_ARGUMENT);
		parent.checkWidget();
	}

	static int checkStyle(Shell parent, int style) {
		int mask = SWT.PRIMARY_MODAL | SWT.APPLICATION_MODAL | SWT.SYSTEM_MODAL;
		if ((style & SWT.SHEET) != 0) {
			style &= ~SWT.SHEET;
			if ((style & mask) == 0) {
				style |= parent == null ? SWT.APPLICATION_MODAL
						: SWT.PRIMARY_MODAL;
			}
		}
		if ((style & mask) == 0) {
			style |= SWT.APPLICATION_MODAL;
		}
		style &= ~SWT.MIRRORED;
		if ((style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT)) == 0) {
			if (parent != null) {
				if ((parent.style & SWT.LEFT_TO_RIGHT) != 0)
					style |= SWT.LEFT_TO_RIGHT;
				if ((parent.style & SWT.RIGHT_TO_LEFT) != 0)
					style |= SWT.RIGHT_TO_LEFT;
			}
		}
		return Widget.checkBits(style, SWT.LEFT_TO_RIGHT, SWT.RIGHT_TO_LEFT, 0,
				0, 0, 0);
	}

	/**
	 * Does whatever dialog specific cleanup is required, and then uses the code
	 * in SWTError.error to handle the error.
	 * 
	 * @param code
	 *            the descriptive error code
	 * 
	 * @see SWT#error(int)
	 */
	void error(int code) {
		SWT.error(code);
	}

	/**
	 * Returns the receiver's parent, which must be a Shell or
	 * null.
	 * 
	 * @return the receiver's parent
	 * 
	 * @exception SWTException
	 *                
	 *                ERROR_WIDGET_DISPOSED - if the receiver has been
	 *                disposed
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the receiver
	 *                
	 */
	public Shell getParent() {
		return parent;
	}

	/**
	 * Returns the receiver's style information.
	 * 
	 * Note that, the value which is returned by this method may
	 * not match the value which was provided to the constructor when the
	 * receiver was created.
	 * 
	 * 
	 * @return the style bits
	 * 
	 * @exception SWTException
	 *                
	 *                ERROR_WIDGET_DISPOSED - if the receiver has been
	 *                disposed
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the receiver
	 *                
	 */
	public int getStyle() {
		return style;
	}

	/**
	 * Returns the receiver's text, which is the string that the window manager
	 * will typically display as the receiver's title. If the text has
	 * not previously been set, returns an empty string.
	 * 
	 * @return the text
	 * 
	 * @exception SWTException
	 *                
	 *                ERROR_WIDGET_DISPOSED - if the receiver has been
	 *                disposed
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the receiver
	 *                
	 */
	public String getText() {
		return title;
	}

	/**
	 * Sets the receiver's text, which is the string that the window manager
	 * will typically display as the receiver's title, to the argument,
	 * which must not be null.
	 * 
	 * @param string
	 *            the new text
	 * 
	 * @exception IllegalArgumentException
	 *                
	 *                ERROR_NULL_ARGUMENT - if the text is null
	 *                
	 * @exception SWTException
	 *                
	 *                ERROR_WIDGET_DISPOSED - if the receiver has been
	 *                disposed
	 *                ERROR_THREAD_INVALID_ACCESS - if not called from the
	 *                thread that created the receiver
	 *                
	 */
	public void setText(String string) {
		if (string == null)
			error(SWT.ERROR_NULL_ARGUMENT);
		title = string;
	}

}