netbeans.apache.org/src/content/wiki/DevFaqDialogsApiIntro.adoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqDialogsApiIntro
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqDialogsApiIntro
:description: Apache NetBeans wiki DevFaqDialogsApiIntro
:toc: left
:toc-title:
:syntax: true

== What is the Dialogs API and How Do I Use It?

The link:https://bits.netbeans.org/dev/javadoc/org-openide-dialogs/[Dialogs API] provides support for dialogs and wizards.

Whenever you'd use JDialog or JOptionPane in Swing, using the Dialogs API provides some alternatives.  These are easier to use as they automatically take care of centering and other display details, but also allow you to later plug in a different implementation of how they're actually "displayed."  Instead of showing them on screen, for example, you could xref:DevFaqLookupHowToOverride.adoc[override the default] `DialogDisplayer` class to specify your own that logged them to a printer or read them aloud using speech synthesis.

I'll illustrate three of the most common use cases.  The first is when you want to simply show a dialog box with some text:
image:OkDialog.png[]

[source,java]
----

String msg = "There is something you should know...";
NotifyDescriptor nd = new NotifyDescriptor.Message(msg, NotifyDescriptor.INFORMATION_MESSAGE);
DialogDisplayer.getDefault().notify(nd);
----

For a question to users, you'll use a similar mechanism.  

image:YesNoDialog.png[]

The `msg` argument is optional here:

[source,java]
----

String msg = "Something is going to happen. Do you want to continue?";
NotifyDescriptor nd = new NotifyDescriptor.Confirmation(msg, NotifyDescriptor.YES_NO_OPTION);
Object result = DialogDisplayer.getDefault().notify(nd);
if (NotifyDescriptor.OK_OPTION == result) {
    // do it
} else {
    // don't do it
}
----

And to request simple user input:

image:InputDialog.png[]

[source,java]
----

String txt = "Name: ";
String title = "State your name";

NotifyDescriptor.InputLine input = new NotifyDescriptor.InputLine(txt, title);
input.setInputText("John Doe"); // specify a default name
Object result = DialogDisplayer.getDefault().notify(input);
if (result != NotifyDescriptor.OK_OPTION) {
    return;
}

String userInput = input.getInputText();
----

And finally, the DialogDescriptor subclass, handles complex cases (there are many variants here; see link:https://bits.netbeans.org/dev/javadoc/org-openide-dialogs/org/openide/DialogDescriptor.html[Dialog Descriptor's Javadoc] for details):

image:CustomPanelDialog.png[]

[source,java]
----

JPanel form = new MyComplexForm();
String msg = "Something bad happened...";
DialogDescriptor dd = new DialogDescriptor(form, msg);
Object result = DialogDisplayer.getDefault().notify(dd);
if (result != NotifyDescriptor.OK_OPTION) {
    return;
}

// you can now examine the form's state...
----

== Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the
Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/DevFaqDialogsApiIntro[http://wiki.netbeans.org/DevFaqDialogsApiIntro] , 
that was last modified by NetBeans user Maehem 
on 2012-11-10T06:16:12Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.