Mnemonicable.java

package org.jdesktop.swingx;

/**
 * An interface that describes an object that is capable of being accessed/used via a mnemonic
 * keystroke.
 * 
 * @author Karl George Schaefer
 */
// TODO this describes the mnemonic feature but not what is used,
// ie. what String returning method is called
interface Mnemonicable {
    /**
     * Returns the keyboard mnemonic for this component.
     * 
     * @return the keyboard mnemonic
     */
    int getMnemonic();

    /**
     * Sets the keyboard mnemonic on this component. The mnemonic is the key
     * which when combined with the look and feel's mouseless modifier (usually
     * Alt) will activate this component.
     * <p>
     * A mnemonic must correspond to a single key on the keyboard and should be
     * specified using one of the <code>VK_XXX</code> keycodes defined in
     * <code>java.awt.event.KeyEvent</code>. Mnemonics are case-insensitive,
     * therefore a key event with the corresponding keycode would cause the
     * button to be activated whether or not the Shift modifier was pressed.
     * 
     * @param mnemonic
     *            the key code which represents the mnemonic
     * @see java.awt.event.KeyEvent
     * @see #setDisplayedMnemonicIndex
     * 
     * @beaninfo bound: true attribute: visualUpdate true description: the
     *           keyboard character mnemonic
     */
    void setMnemonic(int mnemonic);
    
    /**
     * Returns the character, as an index, that the look and feel should
     * provide decoration for as representing the mnemonic character.
     *
     * @since 1.4
     * @return index representing mnemonic character
     * @see #setDisplayedMnemonicIndex
     */
    int getDisplayedMnemonicIndex();

    /**
     * Provides a hint to the look and feel as to which character in the
     * text should be decorated to represent the mnemonic. Not all look and
     * feels may support this. A value of -1 indicates either there is no
     * mnemonic, the mnemonic character is not contained in the string, or
     * the developer does not wish the mnemonic to be displayed.
     * <p>
     * The value of this is updated as the properties relating to the
     * mnemonic change (such as the mnemonic itself, the text...).
     * You should only ever have to call this if
     * you do not wish the default character to be underlined. For example, if
     * the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A'
     * to be decorated, as 'Save <u>A</u>s', you would have to invoke
     * <code>setDisplayedMnemonicIndex(5)</code> after invoking
     * <code>setMnemonic(KeyEvent.VK_A)</code>.
     *
     * @since 1.4
     * @param index Index into the String to underline
     * @exception IllegalArgumentException will be thrown if <code>index</code>
     *            is >= length of the text, or < -1
     * @see #getDisplayedMnemonicIndex
     *
     * @beaninfo
     *        bound: true
     *    attribute: visualUpdate true
     *  description: the index into the String to draw the keyboard character
     *               mnemonic at
     */
    void setDisplayedMnemonicIndex(int index) throws IllegalArgumentException;
}