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

Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.swt.win32.win32.x86 Show documentation
SWT is an open source widget toolkit for Java designed to provide efficient, portable access to the user-interface facilities of the operating systems on which it is implemented.
The newest version!
/*******************************************************************************
 * Copyright (c) 2000, 2011 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.swt.widgets;


import org.eclipse.swt.*;

/**
 * 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;
}

}