org.eclipse.ercp.swt.mobile
Class MultiPageDialog

java.lang.Object
  org.eclipse.swt.widgets.Dialog
      org.eclipse.ercp.swt.mobile.MultiPageDialog

public class MultiPageDialog

extends Dialog

Instances of this class represents a tabbed dialog. The dialog contains multiple pages. Each page contains a composite. At any given time, only one page is visible. The page visibility can be selected by end-users or applications programmatically.

Each page has a label. The platform may display the label as text, an icon, or both together. The size and position of page labels is implementation-dependent.

There is no fixed limit on the number of pages. A run-time exception may be thrown when resources are insufficient to create a new page.

Note: The bounds of this dialog is implementation-dependent. Applications can query the actual page size through page.getBounds after the page has been created.

Commands associated to a page are only visible when that page is visible. Commands may be associated with the whole MultiPageDialog by querying a page's Shell and using it as the Control when creating Commands. For example: Command c = new Command(page.getShell(), Command.GENERAL, 10);

Example:

 MultiPageDialog dialog = new MultiPageDialog(shell);
 Composite page1 = dialog.createPage("Page 1", null);
 // add child controls here 
 Command okCMD = new Command(page1, Command.OK, 1);
 okCMD.setText("Ok");
 okCMD.addSelectionListener(new SelectionListener() {
 	public void widgetSelected(SelectionEvent e) {
 		// do something here before closing the dialog
 		dialog.close(); // Make the dialog invisible
 		dialog.dispose(); // Dispose the dialog and its children.
 	}
  public void widgetDefaultSelected(SelectionEvent e) {}
 });
 dialog.setSelection(dialog.getPageCount() - 1); // The last page
 dialog.open(); // open a modal dialog
 

Styles:

(none)

Events:

Selection

IMPORTANT: This class is not intended to be subclassed.

Constructor Summary

MultiPageDialog(Shell parent)
Constructs a new instance of this class given only its parent.

MultiPageDialog(Shell parent, int style)
Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

Method Summary

void	addSelectionListener(SelectionListener listener) Adds the listener to the collection of listeners who will be notified when the page changes, by sending it one of the messages defined in the SelectionListener interface.
void	close() Requests that the window manager close the dialog in the same way it would be closed when the user clicks on the "close box" or performs some other platform specific key or mouse combination that indicates the window should be removed.
Composite	createPage(java.lang.String title, Image icon) Creates a new page with the specified title string and icon.
void	deletePage(int index) Deletes the page from the receiver at the given zero-relative index
void	dispose() Disposes of the operating system resources associated with the receiver.
Composite	getPage(int index) Returns the composite of the page at the given zero-relative index in the receiver.
int	getPageCount() Returns the number of pages contained in the receiver.
int	getSelectionIndex() Returns the zero-relative index of the page which is currently selected in the receiver, or the newest page created to the receiver.
java.lang.String	getTitle(int index) Returns the title string of the page at the given zero-relative index in the receiver.
void	open() Makes the dialog visible and brings it to the front of the display.
void	removeSelectionListener(SelectionListener listener) Removes the listener from the collection of listeners who will be notified when the receiver's selection changes.
void	setImage(int index, Image icon) Sets the icon image of the page at the given zero-relative index.
void	setSelection(int index) Selects the active page by the given zero-relative index.
void	setTitle(int index, java.lang.String title) Sets the title string of the page at the given zero-relative index.

Methods inherited from class org.eclipse.swt.widgets.Dialog

checkSubclass, getParent, getStyle, getText, setText

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MultiPageDialog

public MultiPageDialog(Shell parent)

Constructs a new instance of this class given only its parent.

Parameters:

parent - a shell which will be the parent of the new instance

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

MultiPageDialog

public MultiPageDialog(Shell parent,
                       int style)

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.

Parameters:

parent - a shell which will be the parent of the new instance

style - the style of dialog to construct

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the parent is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

Method Detail

addSelectionListener

public void addSelectionListener(SelectionListener listener)

Adds the listener to the collection of listeners who will be notified when the page changes, by sending it one of the messages defined in the SelectionListener interface.

When widgetSelected is called, the item field of the event object is valid. widgetDefaultSelected is not called.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

SelectionListener, removeSelectionListener(org.eclipse.swt.events.SelectionListener), SelectionEvent

close

public void close()

Requests that the window manager close the dialog in the same way it would be closed when the user clicks on the "close box" or performs some other platform specific key or mouse combination that indicates the window should be removed. No exception is thrown even when the dialog has been closed by the end-user.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

Shell.close()

createPage

public Composite createPage(java.lang.String title,
                            Image icon)

Creates a new page with the specified title string and icon.

Parameters:

title - - the title string. Cannot be null.

icon - - the label icon image. May be null.

Returns:

composite - the new composite instance in the page. Cannot be null.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the page title is null

SWTException -

• ERROR_ITEM_NOT_ADDED - if the page can not be created
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

deletePage

public void deletePage(int index)

Deletes the page from the receiver at the given zero-relative index

Parameters:

index - - the index value. Cannot be negative, greater or equal to the number of pages.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_RANGE - if the index is not between 0 and the number of pages in the receiver minus 1 (inclusive)

SWTException -

• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

dispose

public void dispose()

Disposes of the operating system resources associated with the receiver. After this method has been invoked, all descendents will answer true when sent the message isDisposed(). Any internal connections between the widgets in the tree will have been removed to facilitate garbage collection.

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

Widget.dispose()

getPage

public Composite getPage(int index)

Returns the composite of the page at the given zero-relative index in the receiver.

Parameters:

index - the index of the page to select. Cannot be negative, greater or equal to the number of pages.

Returns:

Composite the composite.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_RANGE - if the page count is zero, or if the index is negative or greater and equal to the page count

SWTException -

• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

getPageCount

public int getPageCount()

Returns the number of pages contained in the receiver.

Returns:

int the number of pages. Returns zero when the dialog is constructed.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the dialog has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

getTitle

public java.lang.String getTitle(int index)

Returns the title string of the page at the given zero-relative index in the receiver.

Parameters:

index - the index of the page to select.

Returns:

String the title string of the page

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_RANGE - if the page count is zero, or if the index is negative or greater and equal to the page count

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

See Also:

setTitle(int, java.lang.String)

getSelectionIndex

public int getSelectionIndex()

Returns the zero-relative index of the page which is currently selected in the receiver, or the newest page created to the receiver.

Returns:

int the index of the selected page

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

open

public void open()

Makes the dialog visible and brings it to the front of the display. Note: This method does not return until the dialog is closed.

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the dialog
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

removeSelectionListener

public void removeSelectionListener(SelectionListener listener)

Removes the listener from the collection of listeners who will be notified when the receiver's selection changes.

Parameters:

listener - the listener which should no longer be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
• ERROR_WIDGET_DISPOSED - if the dialog has been disposed

See Also:

SelectionListener, addSelectionListener(org.eclipse.swt.events.SelectionListener)

setSelection

public void setSelection(int index)

Selects the active page by the given zero-relative index.

Parameters:

index - the index of the page to select. Cannot be negative, greater or equal to the number of pages.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_RANGE - if the page count is zero, or if the index is negative or greater and equal to the page count

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setImage

public void setImage(int index,
                     Image icon)

Sets the icon image of the page at the given zero-relative index. Note that the icon size is implementation dependent so that the icon image may be stretched or shrunk automatically.

Parameters:

index - the index of the page to select.

icon - the new icon image.

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the icon is null
• ERROR_INVALID_RANGE - if the page count is zero, or if the index is negative or greater and equal to the page count

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setTitle

public void setTitle(int index,
                     java.lang.String title)

Sets the title string of the page at the given zero-relative index.

Parameters:

index - the index of the page to select.

title - the new title string. Cannot be null.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_RANGE - if the page count is zero, or if the index is negative or greater and equal to the page count
• ERROR_NULL_ARGUMENT - if the title is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

getTitle(int)