< prev index next >
src/java.desktop/share/classes/java/awt/event/KeyEvent.java
Print this page
*** 35,50 ****
/**
* An event which indicates that a keystroke occurred in a component.
* <p>
* This low-level event is generated by a component object (such as a text
* field) when a key is pressed, released, or typed.
! * The event is passed to every <code>KeyListener</code>
! * or <code>KeyAdapter</code> object which registered to receive such
! * events using the component's <code>addKeyListener</code> method.
! * (<code>KeyAdapter</code> objects implement the
! * <code>KeyListener</code> interface.) Each such listener object
! * gets this <code>KeyEvent</code> when the event occurs.
* <p>
* <em>"Key typed" events</em> are higher-level and generally do not depend on
* the platform or keyboard layout. They are generated when a Unicode character
* is entered, and are the preferred way to find out about character input.
* In the simplest case, a key typed event is produced by a single key press
--- 35,50 ----
/**
* An event which indicates that a keystroke occurred in a component.
* <p>
* This low-level event is generated by a component object (such as a text
* field) when a key is pressed, released, or typed.
! * The event is passed to every {@code KeyListener}
! * or {@code KeyAdapter} object which registered to receive such
! * events using the component's {@code addKeyListener} method.
! * ({@code KeyAdapter} objects implement the
! * {@code KeyListener} interface.) Each such listener object
! * gets this {@code KeyEvent} when the event occurs.
* <p>
* <em>"Key typed" events</em> are higher-level and generally do not depend on
* the platform or keyboard layout. They are generated when a Unicode character
* is entered, and are the preferred way to find out about character input.
* In the simplest case, a key typed event is produced by a single key press
*** 972,982 ****
public static final char CHAR_UNDEFINED = 0xFFFF;
/**
* A constant indicating that the keyLocation is indeterminate
* or not relevant.
! * <code>KEY_TYPED</code> events do not have a keyLocation; this value
* is used instead.
* @since 1.4
*/
public static final int KEY_LOCATION_UNKNOWN = 0;
--- 972,982 ----
public static final char CHAR_UNDEFINED = 0xFFFF;
/**
* A constant indicating that the keyLocation is indeterminate
* or not relevant.
! * {@code KEY_TYPED} events do not have a keyLocation; this value
* is used instead.
* @since 1.4
*/
public static final int KEY_LOCATION_UNKNOWN = 0;
*** 1026,1036 ****
* @see #setKeyCode(int)
*/
int keyCode;
/**
! * <code>keyChar</code> is a valid unicode character
* that is fired by a key or a key combination on
* a keyboard.
*
* @serial
* @see #getKeyChar()
--- 1026,1036 ----
* @see #setKeyCode(int)
*/
int keyCode;
/**
! * {@code keyChar} is a valid unicode character
* that is fired by a key or a key combination on
* a keyboard.
*
* @serial
* @see #getKeyChar()
*** 1043,1055 ****
*
* Some keys occur more than once on a keyboard, e.g. the left and
* right shift keys. Additionally, some keys occur on the numeric
* keypad. This variable is used to distinguish such keys.
*
! * The only legal values are <code>KEY_LOCATION_UNKNOWN</code>,
! * <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
! * <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
*
* @serial
* @see #getKeyLocation()
*/
int keyLocation;
--- 1043,1055 ----
*
* Some keys occur more than once on a keyboard, e.g. the left and
* right shift keys. Additionally, some keys occur on the numeric
* keypad. This variable is used to distinguish such keys.
*
! * The only legal values are {@code KEY_LOCATION_UNKNOWN},
! * {@code KEY_LOCATION_STANDARD}, {@code KEY_LOCATION_LEFT},
! * {@code KEY_LOCATION_RIGHT}, and {@code KEY_LOCATION_NUMPAD}.
*
* @serial
* @see #getKeyLocation()
*/
int keyLocation;
*** 1113,1128 ****
this(source, id, when, modifiers, keyCode, keyChar, keyLocation);
this.isProxyActive = isProxyActive;
}
/**
! * Constructs a <code>KeyEvent</code> object.
* <p>This method throws an
! * <code>IllegalArgumentException</code> if <code>source</code>
! * is <code>null</code>.
*
! * @param source The <code>Component</code> that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
--- 1113,1128 ----
this(source, id, when, modifiers, keyCode, keyChar, keyLocation);
this.isProxyActive = isProxyActive;
}
/**
! * Constructs a {@code KeyEvent} object.
* <p>This method throws an
! * {@code IllegalArgumentException} if {@code source}
! * is {@code null}.
*
! * @param source The {@code Component} that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
*** 1140,1162 ****
* (for a key-typed event)
* @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
* @param keyLocation Identifies the key location. The only legal
! * values are <code>KEY_LOCATION_UNKNOWN</code>,
! * <code>KEY_LOCATION_STANDARD</code>, <code>KEY_LOCATION_LEFT</code>,
! * <code>KEY_LOCATION_RIGHT</code>, and <code>KEY_LOCATION_NUMPAD</code>.
* @throws IllegalArgumentException
! * if <code>id</code> is <code>KEY_TYPED</code> and
! * <code>keyChar</code> is <code>CHAR_UNDEFINED</code>;
! * or if <code>id</code> is <code>KEY_TYPED</code> and
! * <code>keyCode</code> is not <code>VK_UNDEFINED</code>;
! * or if <code>id</code> is <code>KEY_TYPED</code> and
! * <code>keyLocation</code> is not <code>KEY_LOCATION_UNKNOWN</code>;
! * or if <code>keyLocation</code> is not one of the legal
* values enumerated above.
! * @throws IllegalArgumentException if <code>source</code> is null
* @see #getSource()
* @see #getID()
* @see #getWhen()
* @see #getModifiers()
* @see #getKeyCode()
--- 1140,1162 ----
* (for a key-typed event)
* @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
* @param keyLocation Identifies the key location. The only legal
! * values are {@code KEY_LOCATION_UNKNOWN},
! * {@code KEY_LOCATION_STANDARD}, {@code KEY_LOCATION_LEFT},
! * {@code KEY_LOCATION_RIGHT}, and {@code KEY_LOCATION_NUMPAD}.
* @throws IllegalArgumentException
! * if {@code id} is {@code KEY_TYPED} and
! * {@code keyChar} is {@code CHAR_UNDEFINED};
! * or if {@code id} is {@code KEY_TYPED} and
! * {@code keyCode} is not {@code VK_UNDEFINED};
! * or if {@code id} is {@code KEY_TYPED} and
! * {@code keyLocation} is not {@code KEY_LOCATION_UNKNOWN};
! * or if {@code keyLocation} is not one of the legal
* values enumerated above.
! * @throws IllegalArgumentException if {@code source} is null
* @see #getSource()
* @see #getID()
* @see #getWhen()
* @see #getModifiers()
* @see #getKeyCode()
*** 1194,1209 ****
}
originalSource = source;
}
/**
! * Constructs a <code>KeyEvent</code> object.
* <p> This method throws an
! * <code>IllegalArgumentException</code> if <code>source</code>
! * is <code>null</code>.
*
! * @param source The <code>Component</code> that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
--- 1194,1209 ----
}
originalSource = source;
}
/**
! * Constructs a {@code KeyEvent} object.
* <p> This method throws an
! * {@code IllegalArgumentException} if {@code source}
! * is {@code null}.
*
! * @param source The {@code Component} that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
*** 1220,1235 ****
* @param keyCode The integer code for an actual key, or VK_UNDEFINED
* (for a key-typed event)
* @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
! * @throws IllegalArgumentException if <code>id</code> is
! * <code>KEY_TYPED</code> and <code>keyChar</code> is
! * <code>CHAR_UNDEFINED</code>; or if <code>id</code> is
! * <code>KEY_TYPED</code> and <code>keyCode</code> is not
! * <code>VK_UNDEFINED</code>
! * @throws IllegalArgumentException if <code>source</code> is null
* @see #getSource()
* @see #getID()
* @see #getWhen()
* @see #getModifiers()
* @see #getKeyCode()
--- 1220,1235 ----
* @param keyCode The integer code for an actual key, or VK_UNDEFINED
* (for a key-typed event)
* @param keyChar The Unicode character generated by this event, or
* CHAR_UNDEFINED (for key-pressed and key-released
* events which do not map to a valid Unicode character)
! * @throws IllegalArgumentException if {@code id} is
! * {@code KEY_TYPED} and {@code keyChar} is
! * {@code CHAR_UNDEFINED}; or if {@code id} is
! * {@code KEY_TYPED} and {@code keyCode} is not
! * {@code VK_UNDEFINED}
! * @throws IllegalArgumentException if {@code source} is null
* @see #getSource()
* @see #getID()
* @see #getWhen()
* @see #getModifiers()
* @see #getKeyCode()
*** 1241,1251 ****
KEY_LOCATION_UNKNOWN);
}
/**
* @deprecated as of JDK1.1; use {@link #KeyEvent(Component, int, long, int, int, char)} instead
! * @param source The <code>Component</code> that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
--- 1241,1251 ----
KEY_LOCATION_UNKNOWN);
}
/**
* @deprecated as of JDK1.1; use {@link #KeyEvent(Component, int, long, int, int, char)} instead
! * @param source The {@code Component} that originated the event
* @param id An integer indicating the type of event.
* For information on allowable values, see
* the class description for {@link KeyEvent}
* @param when A long integer that specifies the time the event
* occurred.
*** 1270,1281 ****
/**
* Returns the integer keyCode associated with the key in this event.
*
* @return the integer code for an actual key on the keyboard.
! * (For <code>KEY_TYPED</code> events, the keyCode is
! * <code>VK_UNDEFINED</code>.)
*/
public int getKeyCode() {
return keyCode;
}
--- 1270,1281 ----
/**
* Returns the integer keyCode associated with the key in this event.
*
* @return the integer code for an actual key on the keyboard.
! * (For {@code KEY_TYPED} events, the keyCode is
! * {@code VK_UNDEFINED}.)
*/
public int getKeyCode() {
return keyCode;
}
*** 1288,1308 ****
this.keyCode = keyCode;
}
/**
* Returns the character associated with the key in this event.
! * For example, the <code>KEY_TYPED</code> event for shift + "a"
* returns the value for "A".
* <p>
! * <code>KEY_PRESSED</code> and <code>KEY_RELEASED</code> events
* are not intended for reporting of character input. Therefore,
* the values returned by this method are guaranteed to be
! * meaningful only for <code>KEY_TYPED</code> events.
*
* @return the Unicode character defined for this key event.
* If no valid Unicode character exists for this key event,
! * <code>CHAR_UNDEFINED</code> is returned.
*/
public char getKeyChar() {
return keyChar;
}
--- 1288,1308 ----
this.keyCode = keyCode;
}
/**
* Returns the character associated with the key in this event.
! * For example, the {@code KEY_TYPED} event for shift + "a"
* returns the value for "A".
* <p>
! * {@code KEY_PRESSED} and {@code KEY_RELEASED} events
* are not intended for reporting of character input. Therefore,
* the values returned by this method are guaranteed to be
! * meaningful only for {@code KEY_TYPED} events.
*
* @return the Unicode character defined for this key event.
* If no valid Unicode character exists for this key event,
! * {@code CHAR_UNDEFINED} is returned.
*/
public char getKeyChar() {
return keyChar;
}
*** 1320,1330 ****
* Set the modifiers to indicate additional keys that were held down
* (e.g. shift, ctrl, alt, meta) defined as part of InputEvent.
* <p>
* NOTE: use of this method is not recommended, because many AWT
* implementations do not recognize modifier changes. This is
! * especially true for <code>KEY_TYPED</code> events where the shift
* modifier is changed.
*
* @param modifiers an integer combination of the modifier constants.
* @see InputEvent
* @deprecated as of JDK1.1.4
--- 1320,1330 ----
* Set the modifiers to indicate additional keys that were held down
* (e.g. shift, ctrl, alt, meta) defined as part of InputEvent.
* <p>
* NOTE: use of this method is not recommended, because many AWT
* implementations do not recognize modifier changes. This is
! * especially true for {@code KEY_TYPED} events where the shift
* modifier is changed.
*
* @param modifiers an integer combination of the modifier constants.
* @see InputEvent
* @deprecated as of JDK1.1.4
*** 1345,1356 ****
* Some keys occur more than once on a keyboard, e.g. the left and
* right shift keys. Additionally, some keys occur on the numeric
* keypad. This provides a way of distinguishing such keys.
*
* @return the location of the key that was pressed or released.
! * Always returns <code>KEY_LOCATION_UNKNOWN</code> for
! * <code>KEY_TYPED</code> events.
* @since 1.4
*/
public int getKeyLocation() {
return keyLocation;
}
--- 1345,1356 ----
* Some keys occur more than once on a keyboard, e.g. the left and
* right shift keys. Additionally, some keys occur on the numeric
* keypad. This provides a way of distinguishing such keys.
*
* @return the location of the key that was pressed or released.
! * Always returns {@code KEY_LOCATION_UNKNOWN} for
! * {@code KEY_TYPED} events.
* @since 1.4
*/
public int getKeyLocation() {
return keyLocation;
}
*** 1539,1557 ****
String unknown = Toolkit.getProperty("AWT.unknown", "Unknown");
return unknown + " keyCode: 0x" + Integer.toString(keyCode, 16);
}
/**
! * Returns a <code>String</code> describing the modifier key(s),
* such as "Shift", or "Ctrl+Shift". These strings can be
! * localized by changing the <code>awt.properties</code> file.
* <p>
! * Note that <code>InputEvent.ALT_MASK</code> and
! * <code>InputEvent.BUTTON2_MASK</code> have the same value,
* so the string "Alt" is returned for both modifiers. Likewise,
! * <code>InputEvent.META_MASK</code> and
! * <code>InputEvent.BUTTON3_MASK</code> have the same value,
* so the string "Meta" is returned for both modifiers.
*
* @param modifiers the modifier mask to be processed
* @return string a text description of the combination of modifier
* keys that were held down during the event
--- 1539,1557 ----
String unknown = Toolkit.getProperty("AWT.unknown", "Unknown");
return unknown + " keyCode: 0x" + Integer.toString(keyCode, 16);
}
/**
! * Returns a {@code String} describing the modifier key(s),
* such as "Shift", or "Ctrl+Shift". These strings can be
! * localized by changing the {@code awt.properties} file.
* <p>
! * Note that {@code InputEvent.ALT_MASK} and
! * {@code InputEvent.BUTTON2_MASK} have the same value,
* so the string "Alt" is returned for both modifiers. Likewise,
! * {@code InputEvent.META_MASK} and
! * {@code InputEvent.BUTTON3_MASK} have the same value,
* so the string "Meta" is returned for both modifiers.
*
* @param modifiers the modifier mask to be processed
* @return string a text description of the combination of modifier
* keys that were held down during the event
*** 1593,1604 ****
/**
* Returns whether the key in this event is an "action" key.
* Typically an action key does not fire a unicode character and is
* not a modifier key.
*
! * @return <code>true</code> if the key is an "action" key,
! * <code>false</code> otherwise
*/
public boolean isActionKey() {
switch (keyCode) {
case VK_HOME:
case VK_END:
--- 1593,1604 ----
/**
* Returns whether the key in this event is an "action" key.
* Typically an action key does not fire a unicode character and is
* not a modifier key.
*
! * @return {@code true} if the key is an "action" key,
! * {@code false} otherwise
*/
public boolean isActionKey() {
switch (keyCode) {
case VK_HOME:
case VK_END:
< prev index next >