RFE: Setting text and mnemonic at once

This document describes the expected behaviour of the RFE 27009 implementation (named RFE: [I18N] All text & mnemonic as "An&ything").

The background

When developing easily i18zed applications there arise several problems around representing mnemonic keys:

• JRE doesn't allow non-Latin symbols to serve as mnemonic keys, so one needs to assign Latin mnemonic keys to localized buttons.
• Displaying to application users what symbol is mnemonic is done by underlining this symbol, and because it must be latin one, translated button's/label's text usually looks like [<Non-latin text> (<Latin symbol>), which doesn't look nice from UI's point-of-view.
• In JDK >1.4 appeared an additional property AbstractButton.displayedMnemonicIndex, that represents an index of a character, that the look and feel should provide decoration for as representing the mnemonic character.
  This property was primary intended to allow button names like [Save As...] (instead of [Save As...]), but also allows to build nice-looking i18zed applications: one may make a button look like [<Non-latin text>] by and assigning mnemonic to be some latin symbol and then manually setting displayedMnemonicIndex to, e.g. 6.
  There're several problems here:
  It takes three properties to set a button's text with mnemonic key.
  The English (often original) version of an interface doesn't need to set displayedMnemonicIndex in order to get a nice-looking UI, so it tends to be ommited.
  Manually setting displayedMnemonicIndex is error-prone.

The idea

It would be nice to set three properties of a button: text, mnemonic and displayedMnemonicIndex using only one string value, editable in NetBeans Form Editor.

It will solve many of i18n problems:

• English developers will not care about i18n much and will not bother with extra work to manually set displayedMnemonicIndex, which (that's the real challenge ;-) ), which they don't need in English version of an application.
• Localization engineers (who work directly with the bundles without opening the forms they localize) will not have to manually count displayedMnemonicIndex.

The solution and implementation details

The proposed solution is to use & symbol while editing text property to indicate that the next following letter will serve as mnemonic key.

Setting three properties at once and a lookup, which latin symbol is to be set as (real) mnemonic, is then implemented via a call of a method setLocalizedText of a class org.openide.awt.Mnemonics in NetBeans OpenAPIs.

This feature involves a non-standard extension of Swing APIs, that's why it's considered as non-recommended for general development, and will be:

• Off by default
• Turning it on for the first time will invoke a dialog with detailed explanation of the feature, and its incompatible "nature".
  TODO: Formulate the dialog text

In order to indicate, whether a particular form uses this non-standard extension or not, it's proposed to have a synthetic property "Generate Mnemonics code" for a top-level form container (e.g. JFrame) in "Code Generation" section.

It's also possible to set this property on a component basis, indicating that one specific component doesn't use such technique, or vice versa - while all the form is left untouched, the very one component is using it.

The mnemonics support can also be turned on in global options, then each new created form's "Generate mnemonics" is set to true.