In-Line Error Messages
Explaining User Errors Where They Occur

Jan Benway
updated: Sept 24, 2003



An issuezilla RFE was entered to get this implemented:

In-line errors have been implemented for NetBeans 3.5, but only for wizards. Custom implementations are required to get the same functionality in a dialog box or other component. Note that the appearance of the implemented in-line errors differ from what is described in the document below. In-line errors are now all blue (R=89, G=79, B=191) and there is no visible gray box around the text. Custom implementation of this proposal should match what is implemented for wizards.

This document is intended for people implementing APIs for inline errors, or for people implementing inline errors custom for their own dialog box or other component. If you intend to simply reference an existing inline error framework, then the rules in the style guide should be sufficient.

The Problem

Most dialog boxes and wizard panels have a certain amount of required information.

  • When creating a new file, the user must enter a unique file name.
  • When entering registration information, the user must provide an email address.
  • When mounting a CVS filesystem, the user must log in.
  • When creating a new package a user must enter a package name that follows a certain format.

There are many ways of dealing with these sorts of problems, and throughout the NetBeans UI, the user encounters quite a few.

Sometimes the Next/OK/Finish button is disabled, waiting for the user to fill in what is required:

This approach seems like a good idea, in that it prevents user errors (clicking Next with an invalid entry) but actually what it does is leave the user to figure out what is wrong. Why can't I click Next in the screen above? There is no way to tell from inside this (modal) wizard. In fact the problem is that there is already an object called MemoryView in the selected location.

In other cases, NetBeans lets the user make a mistake and then tells them what the mistake was. For example, this is what happens if I enter an invalid package name and click Finish:

This method, unlike the last, at least tells the user what is wrong. However, the user has to waste several clicks to find this out. They type the name, click Finish, see the error, click OK, then return to editing. If they are unfamiliar with how to construct a valid package name, a user may have to cycle through several times. If they have just made a simple typo, they have several steps needed to correct it.

In the case where simply knowing which fields are required is the issue, some modules mark the required fields. This is done in a variety of ways. This version of the Forte for Java registration wizard used * to mark required fields. Other modules might use bold text, or some other marking mechanism. In most cases, this approach is combined with disabling Next or Finish:

In some cases, there is text explaining what the user must do. For example, in the CVs wizard, choosing "External" requires another step, as explained at the bottom of the panel:

Marking required fields and adding general instruction text helps a lot, but the method of doing so is inconsistent and thus easily missed, even among experienced users. It also doesn't address the entry of invalid information, only that some information is required. It must be used together with one of the first two methods (disabling buttons or giving errors) if the user enters something that is not allowed.

In-Line Error Messages

Combine the button disabling method with an in-line error message. The basic idea is that whenever the user is in an error state, a "status" type message is displayed. When there are no problems or errors, the message goes away:

Example :

How it works:

  • When the error occurs, the message appears at the bottom of the dialog box. This is done at the keystroke level. Messages will appear and disappear as the user types.
  • As soon as the error is fixed, the message goes away.
  • If there is more than one error, the last error made will be shown in the text area at the bottom. Once that error is fixed, the next message (the error before that, or the first error in the panel, doesn't matter much) appears. Multiple errors should happen rarely. See UI guidelines section.
  • For required fields that do not have default values, an error will appear when the dialog box first opens. Since the text is not an alarming color, this is not generally a problem for the user. If showing a message when a dialog first opens is problematic, avoid the issue by providing a default (this way there is no error, as all required fields are filed in).
  • The "status-like" box where the messages appear appears only when there is a message. However, for any panel that implements in-line errors, space is reserved for the box (so the dialog doesn't jump or change in size when a message appears).
  • The text color is this shade of blue: R=89, G=79, B=191

Why this is cool:

  • The messages are transparent:
    • No user actions are needed to dismiss them.
    • They never cover over what the user is doing.
    • If the user just makes a typo and notices it right away, they never have to attend to it at all.
  • Unlike static text, they cover only the problem the user has right now, not all the problems they might have.
  • They change dynamically, so the user knows the instant the problem occurs, and the instant the problem has been solved.
  • It can be done consistently across the IDE, so that we don't have disabled buttons in some places and error alerts in others.
  • The blue color and the perceived "movement" when the text appears attracts attention, but doesn't demand attention.

Propagating the idea across the IDE

This solution works best if applied consistently across the entire IDE. UI Designers and developers need some tools to make this work consistently. So far, this has been implemented for wizards only. The tools include:

API Support:

(Text in this area contributed by Tor Norbye and Svata Dedic. Jan Benway copied and pasted it here from emails)

DialogDescriptor and WizardDescriptor should add a status area to the bottom of the panel so that developers can easily add this functionality. The status area would only appear if explicitly requested by the developer. Adding this API would mean that in-line errors would appear very consistently across the IDE -- they would look the same everywhere (same location, same colors) and they would be used everywhere if they were very easy to implement.

For example, it might look something like:


String message - user desc, or null to clear error
HelpCtx help - optional help if a long description is desirable
JLabel label - optional label to mark with error glyph to "pinpoint" the problem


Since now module writers are encouraged to decouple the wizard panel object from the GUI Component (a warning message is printed at runtime if they don't do that), there could be a support class for the WizardPanel to extend that could simplify stuff for a module writer -- so there could be things like:

addError(Component c, String | Exception message);
clearError(Component c);

UI Guidelines:

NetBeans guidelines would be added to help designers know when and how to use in-line error messages. The guidelines would be:

  • Use an in-line error every time the user may not proceed without correcting an error. There should always be text displayed when OK is disabled and when Next is disabled on the non-terminal page of a wizard and when Finish is disabled on the terminal page of a wizard.
  • Warning information may be displayed at the designer's discretion when all buttons are enabled. For example, a warning stating that a file name the user entered already exists, and the new file will overwrite the old one. In such a case, it may also be necessary to show a warning alert after the user clicks OK/Next/Finish, to confirm that the user wants to overwrite the file..
  • Non-error information may be displayed, again, at the designer's discretion, when all buttons are enabled. For example: The user enters a folder name that does not exist, and the transparent message states that the folder does not exist and will be created. In this case, there is no danger of data loss, and so there is no need to also show an alert after the user commits. Care should be used not to overuse this, however. It is better to redesign the panel if what the user should do is unclear. We may agree to change this guideline, to allow these messages only for errors, or only for errors and warnings.
  • If there are many required fields, provide defaults so that the control buttons are enabled as soon as possible and fewer error messages can be displayed. If all fields are filled in with defaults, an error is only displayed if a user removes required information, or modifies the default entry to something invalid.
  • Required fields typically have at least 2 possible messages, one to indicate that the field is required, and one to ensure the entry is valid. For example, "Enter a file name" for when the field is not filled in, and "File name 'gg hh' is not a valid java class name"
  • For "form"-type dialogs (enter name, street address, etc.) it is acceptable but not required to mark required fields with a * as well as providing inline errors/missing data notices.
  • If there are only a few valid entries a user can make, eliminate the possibility of invalid entries by providing a combo box, radio button, or checkbox control instead of a textfield.
  • The text should be carefully constructed to make it clear which field the error is referring to. It must include the name of the field or the actual text the user entered. Whenever possible, the message should include very specific information and information on how to fix the problem. More information should always be available in the panel's context-sensitive help.
  • Tabbed dialog boxes are a special case. If the user makes an error on one tab and then moves to another, what happens? Here is the behavior:
    • If there an error on any tab, disable the OK button
    • The inline error itself appears only on the tab that contains the error
    • An error icon appears in the tab to the left of the tab name. This way, if the user changes tabs, they see the error icon and can return to fix the problem so as to enable the OK button. For example:


Project Features

About this Project

ui was started in November 2009, is owned by Jiří Kovalský, and has 45 members.
By use of this website, you agree to the NetBeans Policies and Terms of Use (revision 20160708.bf2ac18). © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo
Please Confirm