Package org.eclipse.jface.wizard

Class WizardDialog

  • All Implemented Interfaces:
    IPageChangeProvider, IRunnableContext, IShellProvider, IWizardContainer, IWizardContainer2
    public class WizardDialog
extends TitleAreaDialog
implements IWizardContainer2, IPageChangeProvider
    A dialog to show a wizard to the end user.

    In typical usage, the client instantiates this class with a particular wizard. The dialog serves as the wizard container and orchestrates the presentation of its pages.

    The standard layout is roughly as follows: it has an area at the top containing both the wizard's title, description, and image; the actual wizard page appears in the middle; below that is a progress indicator (which is made visible if needed); and at the bottom of the page is message line and a button bar containing Help, Next, Back, Finish, and Cancel buttons (or some subset).

    Clients may subclass WizardDialog, although this is rarely required.

    • Field Detail

      • WIZ_IMG_ERROR

        public static final String WIZ_IMG_ERROR
        Image registry key for error message image (value "dialog_title_error_image").
        See Also:
        Constant Field Values

    • Constructor Detail

      • WizardDialog

        public WizardDialog​(Shell parentShell,
                    IWizard newWizard)
        Creates a new wizard dialog for the given wizard.
        Parameters:
        parentShell - the parent shell
        newWizard - the wizard this dialog is working on

    • Method Detail

      • setShellStyle

        public void setShellStyle​(int newShellStyle)
        Sets the shell style of the wizard dialog.

        Examples:
        To use the default style without the SWT.APPLICATION_MODAL bit:
        setShellStyle(getShellStyle() & ~SWT.APPLICATION_MODAL)

        To use the default style without the SWT.RESIZE bit:
        setShellStyle(getShellStyle() & ~SWT.RESIZE)

        Sets the shell style bits. This method has no effect after the shell is created.

        The shell style bits are used by the framework method createShell when creating this window's shell.

        Overrides:
        setShellStyle in class Window
        Parameters:
        newShellStyle - the new shell style bits
        See Also:
        setModal(boolean)

      • getShellStyle

        public int getShellStyle()
        Description copied from class: Window
        Returns the shell style bits.

        The default value is SWT.CLOSE|SWT.MIN|SWT.MAX|SWT.RESIZE. Subclasses should call setShellStyle to change this value, rather than overriding this method.

        Overrides:
        getShellStyle in class Window
        Returns:
        the shell style bits

      • setModal

        public WizardDialog setModal​(boolean modal)
        Option to set the modality of the WizardDialog. This method must be called before the dialog's shell is created, e.g. before you call Window.open() for the first time.
        Parameters:
        modal - true (default) if the WizardDialog should block the underlying window.
        Returns:
        this WizardDialog
        Since:
        3.16

      • isModal

        public boolean isModal()
        Returns:
        false if the user interface blocks the underlying window (modal) or true if the underlying window is not blocked.
        Since:
        3.16
        See Also:
        setModal(boolean), setShellStyle(int)

      • backPressed

        protected void backPressed()
        The Back button has been pressed.

      • buttonPressed

        protected void buttonPressed​(int buttonId)
        Description copied from class: Dialog
        Notifies that this dialog's button with the given id has been pressed.

        The Dialog implementation of this framework method calls okPressed if the ok button is the pressed, and cancelPressed if the cancel button is the pressed. All other button presses are ignored. Subclasses may override to handle other buttons, but should call super.buttonPressed if the default handling of the ok and cancel buttons is desired.

        Overrides:
        buttonPressed in class Dialog
        Parameters:
        buttonId - the id of the button that was pressed (see IDialogConstants.*_ID constants)

      • cancelPressed

        protected void cancelPressed()
        Description copied from class: Dialog
        Notifies that the cancel button of this dialog has been pressed.

        The Dialog implementation of this framework method sets this dialog's return code to Window.CANCEL and closes the dialog. Subclasses may override if desired.

        Overrides:
        cancelPressed in class Dialog

      • close

        public boolean close()
        Description copied from class: Window
        Closes this window, disposes its shell, and removes this window from its window manager (if it has one).

        This framework method may be extended (super.close must be called).

        Note that in order to prevent recursive calls to this method it does not call Shell#close(). As a result ShellListeners will not receive a shellClosed event.

        Overrides:
        close in class Dialog
        Returns:
        true if the window is (or was already) closed, and false if it is still open
        See Also:
        Window.close()

      • configureShell

        protected void configureShell​(Shell newShell)
        Description copied from class: Window
        Configures the given shell in preparation for opening this window in it.

        The default implementation of this framework method sets the shell's image and gives it a grid layout. Subclasses may extend or reimplement.

        Overrides:
        configureShell in class Window
        Parameters:
        newShell - the shell

      • createButtonsForButtonBar

        protected void createButtonsForButtonBar​(Composite parent)
        Creates the buttons for this dialog's button bar.

        The WizardDialog implementation of this framework method prevents the parent composite's columns from being made equal width in order to remove the margin between the Back and Next buttons.

        Overrides:
        createButtonsForButtonBar in class Dialog
        Parameters:
        parent - the parent composite to contain the buttons

      • setButtonLayoutData

        protected void setButtonLayoutData​(Button button)
        Description copied from class: Dialog
        Set the layout data of the button to a GridData with appropriate heights and widths.
        Overrides:
        setButtonLayoutData in class Dialog
        Parameters:
        button - The button which layout data is to be set.

      • createContents

        protected Control createContents​(Composite parent)
        The WizardDialog implementation of this Window method calls call IWizard.addPages to allow the current wizard to add extra pages, then super.createContents to create the controls. It then calls IWizard.createPageControls to allow the wizard to pre-create their page controls prior to opening, so that the wizard opens to the correct size. And finally it shows the first page.
        Overrides:
        createContents in class TitleAreaDialog
        Parameters:
        parent - the parent composite for the controls in this window. The type of layout used is determined by getLayout()
        Returns:
        the control that will be returned by subsequent calls to getContents()

      • createDialogArea

        protected Control createDialogArea​(Composite parent)
        Description copied from class: TitleAreaDialog
        Creates and returns the contents of the upper part of this dialog (above the button bar).

        The Dialog implementation of this framework method creates and returns a new Composite with no margins and spacing. Subclasses should override.

        Overrides:
        createDialogArea in class TitleAreaDialog
        Parameters:
        parent - The parent composite to contain the dialog area
        Returns:
        the dialog area control

      • createProgressMonitorPart

        protected ProgressMonitorPart createProgressMonitorPart​(Composite composite,
                                                        GridLayout pmlayout)
        Hook method for subclasses to create a custom progress monitor part.

        The default implementation creates a progress monitor with a stop button will be created.

        Parameters:
        composite - the parent composite
        pmlayout - the layout
        Returns:
        ProgressMonitorPart the progress monitor part

      • finishPressed

        protected void finishPressed()
        The Finish button has been pressed.

      • getProgressMonitor

        protected IProgressMonitor getProgressMonitor()
        Returns the progress monitor for this wizard dialog (if it has one).
        Returns:
        the progress monitor, or null if this wizard dialog does not have one

      • getWizard

        protected IWizard getWizard()
        Returns the wizard this dialog is currently displaying.
        Returns:
        the current wizard

      • helpPressed

        protected void helpPressed()
        The Help button has been pressed.

      • nextPressed

        protected void nextPressed()
        The Next button has been pressed.

      • run

        public void run​(boolean fork,
                boolean cancelable,
                IRunnableWithProgress runnable)
         throws InvocationTargetException,
                InterruptedException
        This implementation of IRunnableContext#run(boolean, boolean, IRunnableWithProgress) blocks until the runnable has been run, regardless of the value of fork. It is recommended that fork is set to true in most cases. If fork is set to false, the runnable will run in the UI thread and it is the runnable's responsibility to call Display.readAndDispatch() to ensure UI responsiveness. UI state is saved prior to executing the long-running operation and is restored after the long-running operation completes executing. Any attempt to change the UI state of the wizard in the long-running operation will be nullified when original UI state is restored.
        Specified by:
        run in interface IRunnableContext
        Parameters:
        fork - true if the runnable should be run in a separate thread, and false to run in the same thread
        cancelable - true to enable the cancelation, and false to make the operation uncancellable
        runnable - the runnable to run
        Throws:
        InvocationTargetException - wraps any exception or error which occurs while running the runnable
        InterruptedException - propagated by the context if the runnable acknowledges cancelation by throwing this exception. This should not be thrown if cancelable is false.

      • setMinimumPageSize

        public void setMinimumPageSize​(int minWidth,
                               int minHeight)
        Sets the minimum page size used for the pages.
        Parameters:
        minWidth - the minimum page width
        minHeight - the minimum page height
        See Also:
        setMinimumPageSize(Point)

      • setMinimumPageSize

        public void setMinimumPageSize​(Point size)
        Sets the minimum page size used for the pages.
        Parameters:
        size - the page size encoded as new Point(width,height)
        See Also:
        setMinimumPageSize(int,int)

      • setPageSize

        public void setPageSize​(int width,
                        int height)
        Sets the size of all pages. The given size takes precedence over computed sizes.
        Parameters:
        width - the page width
        height - the page height
        See Also:
        setPageSize(Point)

      • setPageSize

        public void setPageSize​(Point size)
        Sets the size of all pages. The given size takes precedence over computed sizes.
        Parameters:
        size - the page size encoded as new Point(width,height)
        See Also:
        setPageSize(int,int)

      • setWizard

        protected void setWizard​(IWizard newWizard)
        Sets the wizard this dialog is currently displaying.
        Parameters:
        newWizard - the wizard

      • showPage

        public void showPage​(IWizardPage page)
        Description copied from interface: IWizardContainer
        Makes the given page visible.

        This method should not be use for normal page sequencing (back, next) which is handled by the container itself. It may, however, be used to move to another page in response to some custom action such as double clicking in a list.

        Specified by:
        showPage in interface IWizardContainer
        Parameters:
        page - the page to show
        See Also:
        IWizardContainer.getCurrentPage()

      • update

        protected void update()
        Updates this dialog's controls to reflect the current page.

      • updateButtons

        public void updateButtons()
        Description copied from interface: IWizardContainer
        Adjusts the enable state of the Back, Next, and Finish buttons to reflect the state of the currently active page in this container.

        This method is called by the container itself when its wizard page changes and may be called by the page at other times to force a button state update.

        Specified by:
        updateButtons in interface IWizardContainer

      • updateMessage

        public void updateMessage()
        Description copied from interface: IWizardContainer
        Updates the message (or error message) shown in the message line to reflect the state of the currently active page in this container.

        This method is called by the container itself when its wizard page changes and may be called by the page at other times to force a message update.

        Specified by:
        updateMessage in interface IWizardContainer

      • updateSize

        protected void updateSize​(IWizardPage page)
        Computes the correct dialog size for the current page and resizes its shell if necessary. Also causes the container to refresh its layout.
        Parameters:
        page - the wizard page to use to resize the dialog
        Since:
        2.0

      • updateSize

        public void updateSize()
        Description copied from interface: IWizardContainer2
        Updates the window size to reflect the state of the current wizard.

        This method is called by the container itself when its wizard changes and may be called by the wizard at other times to force a window size change.

        Specified by:
        updateSize in interface IWizardContainer2

      • updateTitleBar

        public void updateTitleBar()
        Description copied from interface: IWizardContainer
        Updates the title bar (title, description, and image) to reflect the state of the currently active page in this container.

        This method is called by the container itself when its wizard page changes and may be called by the page at other times to force a title bar update.

        Specified by:
        updateTitleBar in interface IWizardContainer

      • updateWindowTitle

        public void updateWindowTitle()
        Description copied from interface: IWizardContainer
        Updates the window title to reflect the state of the current wizard.

        This method is called by the container itself when its wizard changes and may be called by the wizard at other times to force a window title change.

        Specified by:
        updateWindowTitle in interface IWizardContainer

      • getSelectedPage

        public Object getSelectedPage()
        Description copied from interface: IPageChangeProvider
        Returns the currently selected page in the dialog.
        Specified by:
        getSelectedPage in interface IPageChangeProvider
        Returns:
        the selected page in the dialog or null if none is selected. The type may be domain specific. In the JFace provided dialogs this will be an instance of IDialogPage.

      • addPageChangingListener

        public void addPageChangingListener​(IPageChangingListener listener)
        Adds a listener for page changes to the list of page changing listeners registered for this dialog. Has no effect if an identical listener is already registered.
        Parameters:
        listener - a page changing listener
        Since:
        3.3

      • removePageChangingListener

        public void removePageChangingListener​(IPageChangingListener listener)
        Removes the provided page changing listener from the list of page changing listeners registered for the dialog.
        Parameters:
        listener - a page changing listener
        Since:
        3.3