001package org.jdesktop.swingx;
002
003/**
004 * An interface that describes an object that is capable of being accessed/used via a mnemonic
005 * keystroke.
006 * 
007 * @author Karl George Schaefer
008 */
009// TODO this describes the mnemonic feature but not what is used,
010// ie. what String returning method is called
011interface Mnemonicable {
012    /**
013     * Returns the keyboard mnemonic for this component.
014     * 
015     * @return the keyboard mnemonic
016     */
017    int getMnemonic();
018
019    /**
020     * Sets the keyboard mnemonic on this component. The mnemonic is the key
021     * which when combined with the look and feel's mouseless modifier (usually
022     * Alt) will activate this component.
023     * <p>
024     * A mnemonic must correspond to a single key on the keyboard and should be
025     * specified using one of the <code>VK_XXX</code> keycodes defined in
026     * <code>java.awt.event.KeyEvent</code>. Mnemonics are case-insensitive,
027     * therefore a key event with the corresponding keycode would cause the
028     * button to be activated whether or not the Shift modifier was pressed.
029     * 
030     * @param mnemonic
031     *            the key code which represents the mnemonic
032     * @see java.awt.event.KeyEvent
033     * @see #setDisplayedMnemonicIndex
034     * 
035     * @beaninfo bound: true attribute: visualUpdate true description: the
036     *           keyboard character mnemonic
037     */
038    void setMnemonic(int mnemonic);
039    
040    /**
041     * Returns the character, as an index, that the look and feel should
042     * provide decoration for as representing the mnemonic character.
043     *
044     * @since 1.4
045     * @return index representing mnemonic character
046     * @see #setDisplayedMnemonicIndex
047     */
048    int getDisplayedMnemonicIndex();
049
050    /**
051     * Provides a hint to the look and feel as to which character in the
052     * text should be decorated to represent the mnemonic. Not all look and
053     * feels may support this. A value of -1 indicates either there is no
054     * mnemonic, the mnemonic character is not contained in the string, or
055     * the developer does not wish the mnemonic to be displayed.
056     * <p>
057     * The value of this is updated as the properties relating to the
058     * mnemonic change (such as the mnemonic itself, the text...).
059     * You should only ever have to call this if
060     * you do not wish the default character to be underlined. For example, if
061     * the text was 'Save As', with a mnemonic of 'a', and you wanted the 'A'
062     * to be decorated, as 'Save <u>A</u>s', you would have to invoke
063     * <code>setDisplayedMnemonicIndex(5)</code> after invoking
064     * <code>setMnemonic(KeyEvent.VK_A)</code>.
065     *
066     * @since 1.4
067     * @param index Index into the String to underline
068     * @exception IllegalArgumentException will be thrown if <code>index</code>
069     *            is &gt;= length of the text, or &lt; -1
070     * @see #getDisplayedMnemonicIndex
071     *
072     * @beaninfo
073     *        bound: true
074     *    attribute: visualUpdate true
075     *  description: the index into the String to draw the keyboard character
076     *               mnemonic at
077     */
078    void setDisplayedMnemonicIndex(int index) throws IllegalArgumentException;
079}