Class DialogDisplayer

java.lang.Object
org.openide.DialogDisplayer
public abstract class DialogDisplayer extends Object
Permits dialogs to be displayed.
Since:
3.14

  • Constructor Details

    • DialogDisplayer

      protected DialogDisplayer()
      Subclass constructor.

  • Method Details

    • getDefault

      public static DialogDisplayer getDefault()
      Get the default dialog displayer.
      Returns:
      the default instance from lookup

    • notify

      public abstract Object notify(NotifyDescriptor descriptor)
      Notify the user of something in a message box, possibly with feedback.

      To support both GUI and non-GUI use, this method may be called from any thread (providing you are not holding any locks), and will block the caller's thread. In GUI mode, it will be run in the AWT event thread automatically. If you wish to hold locks, or do not need the result object immediately or at all, please make this call asynchronously (e.g. from the request processor).

      Parameters:
      descriptor - description of the notification
      Returns:
      the option that caused the message box to be closed

    • notifyLater

      public void notifyLater(NotifyDescriptor descriptor)
      Notify the user of something in a message box, possibly with feedback, this method may be called from any thread. The thread will return immediately and the dialog will be shown later, usually when AWT thread is empty and can handle the request.

      Implementation note: Since version 7.3, implementation improved to work also before main window is opened. For example: When method is called from ModuleInstall.restored, then modal dialog is opened and blocks main window until dialog is closed. Typical use case is login dialog.

      Parameters:
      descriptor - description of the notification
      Since:
      7.0

    • notifyFuture

      public <T extends NotifyDescriptor> CompletableFuture<T> notifyFuture(T descriptor)
      Notify the user by a message box. The method may be called from any thread; the method returns immediately and the UI will be shown later, as in notifyLater(NotifyDescriptor). Unlike notifyLater(NotifyDescriptor), this method returns a CompletableFuture that will be completed when the UI closes. The value of the returned CompletableFuture is the descriptor itself: it's NotifyDescriptor.getValue() will be set to the closing option. If a subclass, like NotifyDescriptor.InputLine is used, the task can query other values of NotifyDescriptor, such as the text entered. Any exception thrown by NotifyDescriptor processing will be reported through CompletableFuture.completeExceptionally(Throwable).

      It is possible to call CompletableFuture.cancel(boolean) on the returned value. The implementation may (through it is not guaranteed) abort and hide the UI. If cancel() is called, the returned Future always completes exceptionally, with a CancellationException.

      The thread that will execute the continuation or exception handler is undefined. Use usual precautions against EDT blocking and use CompletableFuture.thenAcceptAsync(java.util.function.Consumer, java.util.concurrent.Executor) or similar to execute in a specific thread. Prefer usage of RequestProcessor to the builtin thread pool.

      The following snippet is an example of chained dialogs (can be any other processing): 
      NotifyDescriptor.InputLine nd = new NotifyDescriptor.InputLine("Question", "Title");

CompletableFuture<UserData> resultFuture = DialogDisplayer.getDefault().notifyFuture(nd).
        // compose with processing after dialog confirmation
        thenCompose(d -> {
            UserData userData = new UserData();
            // this code will NOT execute, if user cancels "Question" dialog. Neither will execute subsequent steps.
            userData.answer1 = d.getInputText();
            // do something with user input and display another question
            NotifyDescriptor.InputLine nd2 = new NotifyDescriptor.InputLine("Question2", "Title");

            return DialogDisplayer.getDefault().notifyFuture(nd).
                thenApply(x -> {
                // pass userData to the next step.
                // This code will NOT execute if the Question2 dialog is cancelled.
                userData.answer2 = x.getInputText();
                return userData;
            });
        }).thenApply((data) -> {
            // This code will not execute if Question or Question2 is cancelled.
            // do some finalization steps.
            return data;
        }).exceptionally(ex -> {
            // JDK-8233050: JDK reports direct exception from the immediate stage, but wrapped one from earlier stages.
            if (ex instanceof CompletionException) {
                ex = ex.getCause();
            }
            // reached if Question, Question2 is cancelled or if some error occurs.
            if (!(ex instanceof CancellationException)) {
                // do error handling
            }
            return null;
        });
      Type Parameters:
      T - actual subclass of NotifyDescriptor passed as a parameter.
      Parameters:
      descriptor - describes the UI / dialog.
      Returns:
      the descriptor instance.
      Since:
      7.61

    • createDialog

      public abstract Dialog createDialog(DialogDescriptor descriptor)
      Get a new standard dialog. The dialog is designed and created as specified in the parameter. Anyone who wants a dialog with standard buttons and standard behavior should use this method.

      Do not cache the resulting dialog if it is modal and try to reuse it! Always create a new dialog using this method if you need to show a dialog again. Otherwise previously closed windows can reappear.

      Parameters:
      descriptor - general description of the dialog
      Returns:
      the new dialog

    • createDialog

      public Dialog createDialog(DialogDescriptor descriptor, Frame parent)
      Same as #createDialog(org.openide.DialogDescriptor) except that it's possible to specify dialog's parent Frame window. When a document window is floated and has focus then new dialog window will use it as a parent window by default. That means non-modal dialogs will close when that document window is closed. To avoid such situation pass WindowManager.getDefault().getMainWindow() as dialog parent window.
      Parameters:
      descriptor - general description of the dialog
      parent - Dialgo parent frame.
      Returns:
      New dialog
      Since:
      7.38