001: /*
002: * Copyright (c) 2006 World Wide Web Consortium,
003: *
004: * (Massachusetts Institute of Technology, European Research Consortium for
005: * Informatics and Mathematics, Keio University). All Rights Reserved. This
006: * work is distributed under the W3C(r) Software License [1] in the hope that
007: * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008: * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009: *
010: * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011: */
012:
013: package org.w3c.dom.events;
014:
015: import org.w3c.dom.views.AbstractView;
016:
017: /**
018: * The <code>KeyboardEvent</code> interface provides specific contextual
019: * information associated with keyboard devices. Each keyboard event
020: * references a key using an identifier. Keyboard events are commonly
021: * directed at the element that has the focus.
022: * <p> The <code>KeyboardEvent</code> interface provides convenient attributes
023: * for some common modifiers keys: <code>KeyboardEvent.ctrlKey</code>,
024: * <code>KeyboardEvent.shiftKey</code>, <code>KeyboardEvent.altKey</code>,
025: * <code>KeyboardEvent.metaKey</code>. These attributes are equivalent to
026: * use the method
027: * <code>KeyboardEvent.getModifierState(keyIdentifierArg)</code> with
028: * "Control", "Shift", "Alt", or "Meta" respectively.
029: * <p> To create an instance of the <code>KeyboardEvent</code> interface, use
030: * the <code>DocumentEvent.createEvent("KeyboardEvent")</code> method call.
031: * <p>See also the <a href='http://www.w3.org/TR/2006/WD-DOM-Level-3-Events-20060413'>
032: Document Object Model (DOM) Level 3 Events Specification
033: </a>.
034: * @since DOM Level 3
035: */
036: public interface KeyboardEvent extends UIEvent {
037: // KeyLocationCode
038: /**
039: * The key activation is not distinguished as the left or right version
040: * of the key, and did not originate from the numeric keypad (or did not
041: * originate with a virtual key corresponding to the numeric keypad).
042: * Example: the 'Q' key on a PC 101 Key US keyboard.
043: */
044: public static final int DOM_KEY_LOCATION_STANDARD = 0x00;
045: /**
046: * The key activated is in the left key location (there is more than one
047: * possible location for this key). Example: the left Shift key on a PC
048: * 101 Key US keyboard.
049: */
050: public static final int DOM_KEY_LOCATION_LEFT = 0x01;
051: /**
052: * The key activation is in the right key location (there is more than
053: * one possible location for this key). Example: the right Shift key on
054: * a PC 101 Key US keyboard.
055: */
056: public static final int DOM_KEY_LOCATION_RIGHT = 0x02;
057: /**
058: * The key activation originated on the numeric keypad or with a virtual
059: * key corresponding to the numeric keypad. Example: the '1' key on a PC
060: * 101 Key US keyboard located on the numeric pad.
061: */
062: public static final int DOM_KEY_LOCATION_NUMPAD = 0x03;
063:
064: /**
065: * <code>keyIdentifier</code> holds the identifier of the key. The key
066: * identifiers are defined in Appendix A.2 "". Implementations that are
067: * unable to identify a key must use the key identifier
068: * <code>"Unidentified"</code>.
069: */
070: public String getKeyIdentifier();
071:
072: /**
073: * The <code>keyLocation</code> attribute contains an indication of the
074: * location of they key on the device, as described in .
075: */
076: public int getKeyLocation();
077:
078: /**
079: * <code>true</code> if the control (Ctrl) key modifier is activated.
080: */
081: public boolean getCtrlKey();
082:
083: /**
084: * <code>true</code> if the shift (Shift) key modifier is activated.
085: */
086: public boolean getShiftKey();
087:
088: /**
089: * <code>true</code> if the alternative (Alt) key modifier is activated.
090: * <p ><b>Note:</b> The Option key modifier on Macintosh systems must be
091: * represented using this key modifier.
092: */
093: public boolean getAltKey();
094:
095: /**
096: * <code>true</code> if the meta (Meta) key modifier is activated.
097: * <p ><b>Note:</b> The Command key modifier on Macintosh systems must be
098: * represented using this key modifier.
099: */
100: public boolean getMetaKey();
101:
102: /**
103: * This methods queries the state of a modifier using a key identifier.
104: * See also .
105: * @param keyIdentifierArg A modifier key identifier. Common modifier
106: * keys are <code>"Alt"</code>, <code>"AltGraph"</code>,
107: * <code>"CapsLock"</code>, <code>"Control"</code>, <code>"Meta"</code>
108: * , <code>"NumLock"</code>, <code>"Scroll"</code>, or
109: * <code>"Shift"</code>.
110: * <p ><b>Note:</b> If an application wishes to distinguish between
111: * right and left modifiers, this information could be deduced using
112: * keyboard events and <code>KeyboardEvent.keyLocation</code>.
113: * @return <code>true</code> if it is modifier key and the modifier is
114: * activated, <code>false</code> otherwise.
115: */
116: public boolean getModifierState(String keyIdentifierArg);
117:
118: /**
119: * The <code>initKeyboardEvent</code> method is used to initialize the
120: * value of a <code>KeyboardEvent</code> object and has the same
121: * behavior as <code>UIEvent.initUIEvent()</code>. The value of
122: * <code>UIEvent.detail</code> remains undefined.
123: * @param typeArg Refer to the <code>UIEvent.initUIEvent()</code> method
124: * for a description of this parameter.
125: * @param canBubbleArg Refer to the <code>UIEvent.initUIEvent()</code>
126: * method for a description of this parameter.
127: * @param cancelableArg Refer to the <code>UIEvent.initUIEvent()</code>
128: * method for a description of this parameter.
129: * @param viewArg Refer to the <code>UIEvent.initUIEvent()</code> method
130: * for a description of this parameter.
131: * @param keyIdentifierArg Specifies
132: * <code>KeyboardEvent.keyIdentifier</code>.
133: * @param keyLocationArg Specifies <code>KeyboardEvent.keyLocation</code>
134: * .
135: * @param modifiersList A <a href='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-S'>white space</a> separated list of modifier key identifiers to be activated on this
136: * object.
137: */
138: public void initKeyboardEvent(String typeArg, boolean canBubbleArg,
139: boolean cancelableArg, AbstractView viewArg,
140: String keyIdentifierArg, int keyLocationArg,
141: String modifiersList);
142:
143: /**
144: * The <code>initKeyboardEventNS</code> method is used to initialize the
145: * value of a <code>KeyboardEvent</code> object and has the same
146: * behavior as <code>UIEvent.initUIEventNS()</code>. The value of
147: * <code>UIEvent.detail</code> remains undefined.
148: * @param namespaceURI Refer to the <code>UIEvent.initUIEventNS()</code>
149: * method for a description of this parameter.
150: * @param typeArg Refer to the <code>UIEvent.initUIEventNS()</code>
151: * method for a description of this parameter.
152: * @param canBubbleArg Refer to the <code>UIEvent.initUIEventNS()</code>
153: * method for a description of this parameter.
154: * @param cancelableArg Refer to the <code>UIEvent.initUIEventNS()</code>
155: * method for a description of this parameter.
156: * @param viewArg Refer to the <code>UIEvent.initUIEventNS()</code>
157: * method for a description of this parameter.
158: * @param keyIdentifierArg Refer to the
159: * <code>KeyboardEvent.initKeyboardEvent()</code> method for a
160: * description of this parameter.
161: * @param keyLocationArg Refer to the
162: * <code>KeyboardEvent.initKeyboardEvent()</code> method for a
163: * description of this parameter.
164: * @param modifiersList A <a href='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-S'>white space</a> separated list of modifier key identifiers to be activated on this
165: * object. As an example, <code>"Control Alt"</code> will activated
166: * the control and alt modifiers.
167: */
168: public void initKeyboardEventNS(String namespaceURI,
169: String typeArg, boolean canBubbleArg,
170: boolean cancelableArg, AbstractView viewArg,
171: String keyIdentifierArg, int keyLocationArg,
172: String modifiersList);
173:
174: }
|