0001: /*
0002: * Copyright 2007 Google Inc.
0003: *
0004: * Licensed under the Apache License, Version 2.0 (the "License"); you may not
0005: * use this file except in compliance with the License. You may obtain a copy of
0006: * the License at
0007: *
0008: * http://www.apache.org/licenses/LICENSE-2.0
0009: *
0010: * Unless required by applicable law or agreed to in writing, software
0011: * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
0012: * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
0013: * License for the specific language governing permissions and limitations under
0014: * the License.
0015: */
0016: package com.google.gwt.user.client;
0017:
0018: import com.google.gwt.core.client.GWT;
0019: import com.google.gwt.core.client.GWT.UncaughtExceptionHandler;
0020: import com.google.gwt.user.client.impl.DOMImpl;
0021:
0022: import java.util.ArrayList;
0023:
0024: /**
0025: * This class provides a set of static methods that allow you to manipulate the
0026: * browser's Document Object Model (DOM). It contains methods for manipulating
0027: * both {@link com.google.gwt.user.client.Element elements} and
0028: * {@link com.google.gwt.user.client.Event events}.
0029: */
0030: public class DOM {
0031:
0032: // The current event being fired
0033: private static Event currentEvent = null;
0034: private static final DOMImpl impl = GWT.create(DOMImpl.class);
0035: private static Element sCaptureElem;
0036:
0037: // <BrowserEventPreview>
0038: private static ArrayList<EventPreview> sEventPreviewStack;
0039:
0040: /**
0041: * Adds an event preview to the preview stack. As long as this preview remains
0042: * on the top of the stack, it will receive all events before they are fired
0043: * to their listeners. Note that the event preview will receive <u>all </u>
0044: * events, including those received due to bubbling, whereas normal event
0045: * handlers only receive explicitly sunk events.
0046: *
0047: * @param preview the event preview to be added to the stack.
0048: */
0049: public static void addEventPreview(EventPreview preview) {
0050: // Add the event preview to the stack. It will automatically
0051: // begin receiving events.
0052: if (sEventPreviewStack == null) {
0053: sEventPreviewStack = new ArrayList<EventPreview>();
0054: }
0055: sEventPreviewStack.add(preview);
0056: }
0057:
0058: /**
0059: * Appends one element to another's list of children.
0060: *
0061: * @param parent the parent element
0062: * @param child its new child
0063: */
0064: public static void appendChild(Element parent, Element child) {
0065: impl.appendChild(parent, child);
0066: }
0067:
0068: /**
0069: * Compares two elements for equality (note that reference equality is not
0070: * sufficient to determine equality among elements on most browsers).
0071: *
0072: * @param elem1 the first element to be compared
0073: * @param elem2 the second element to be compared
0074: * @return <code>true</code> if they are in fact the same element
0075: * @see #isOrHasChild(Element, Element)
0076: */
0077: public static boolean compare(Element elem1, Element elem2) {
0078: return impl.compare(elem1, elem2);
0079: }
0080:
0081: /**
0082: * Creates an HTML A element.
0083: *
0084: * @return the newly-created element
0085: */
0086: public static Element createAnchor() {
0087: return impl.createElement("A");
0088: }
0089:
0090: /**
0091: * Creates an HTML BUTTON element.
0092: *
0093: * @return the newly-created element
0094: */
0095: public static Element createButton() {
0096: return impl.createElement("button");
0097: }
0098:
0099: /**
0100: * Creates an HTML CAPTION element.
0101: *
0102: * @return the newly-created element
0103: */
0104: public static Element createCaption() {
0105: return impl.createElement("caption");
0106: }
0107:
0108: /**
0109: * Creates an HTML COL element.
0110: *
0111: * @return the newly-created element
0112: */
0113: public static Element createCol() {
0114: return impl.createElement("col");
0115: }
0116:
0117: /**
0118: * Creates an HTML COLGROUP element.
0119: *
0120: * @return the newly-created element
0121: */
0122: public static Element createColGroup() {
0123: return impl.createElement("colgroup");
0124: }
0125:
0126: /**
0127: * Creates an HTML DIV element.
0128: *
0129: * @return the newly-created element
0130: */
0131: public static Element createDiv() {
0132: return impl.createElement("div");
0133: }
0134:
0135: /**
0136: * Creates an HTML element.
0137: *
0138: * @param tagName the HTML tag of the element to be created
0139: * @return the newly-created element
0140: */
0141: public static Element createElement(String tagName) {
0142: return impl.createElement(tagName);
0143: }
0144:
0145: /**
0146: * Creates an HTML FIELDSET element.
0147: *
0148: * @return the newly-created element
0149: */
0150: public static Element createFieldSet() {
0151: return impl.createElement("fieldset");
0152: }
0153:
0154: /**
0155: * Creates an HTML FORM element.
0156: *
0157: * @return the newly-created element
0158: */
0159: public static Element createForm() {
0160: return impl.createElement("form");
0161: }
0162:
0163: /**
0164: * Creates an HTML IFRAME element.
0165: *
0166: * @return the newly-created element
0167: */
0168: public static Element createIFrame() {
0169: return impl.createElement("iframe");
0170: }
0171:
0172: /**
0173: * Creates an HTML IMG element.
0174: *
0175: * @return the newly-created element
0176: */
0177: public static Element createImg() {
0178: return impl.createElement("img");
0179: }
0180:
0181: /**
0182: * Creates an HTML INPUT type='CHECK' element.
0183: *
0184: * @return the newly-created element
0185: */
0186: public static Element createInputCheck() {
0187: return impl.createInputElement("checkbox");
0188: }
0189:
0190: /**
0191: * Creates an HTML INPUT type='PASSWORD' element.
0192: *
0193: * @return the newly-created element
0194: */
0195: public static Element createInputPassword() {
0196: return impl.createInputElement("password");
0197: }
0198:
0199: /**
0200: * Creates an HTML INPUT type='RADIO' element.
0201: *
0202: * @param name the name of the group with which this radio button will be
0203: * associated
0204: * @return the newly-created element
0205: */
0206: public static Element createInputRadio(String name) {
0207: return impl.createInputRadioElement(name);
0208: }
0209:
0210: /**
0211: * Creates an HTML INPUT type='TEXT' element.
0212: *
0213: * @return the newly-created element
0214: */
0215: public static Element createInputText() {
0216: return impl.createInputElement("text");
0217: }
0218:
0219: /**
0220: * Creates an HTML LABEL element.
0221: *
0222: * @return the newly-created element
0223: */
0224: public static Element createLabel() {
0225: return impl.createElement("label");
0226: }
0227:
0228: /**
0229: * Creates an HTML LEGEND element.
0230: *
0231: * @return the newly-created element
0232: */
0233: public static Element createLegend() {
0234: return impl.createElement("legend");
0235: }
0236:
0237: /**
0238: * Creates an HTML OPTIONS element.
0239: *
0240: * @return the newly-created element
0241: */
0242: public static Element createOptions() {
0243: return impl.createElement("options");
0244: }
0245:
0246: /**
0247: * Creates a single-selection HTML SELECT element. Equivalent to
0248: *
0249: * <pre>
0250: * createSelect(false)
0251: * </pre>
0252: *
0253: * @return the newly-created element
0254: */
0255: public static Element createSelect() {
0256: return DOM.createSelect(false);
0257: }
0258:
0259: /**
0260: * Creates an HTML SELECT element.
0261: *
0262: * @param multiple true if multiple selection of options is allowed
0263: * @return the newly-created element
0264: */
0265: public static Element createSelect(boolean multiple) {
0266: return impl.createSelectElement(multiple);
0267: }
0268:
0269: /**
0270: * Creates an HTML SPAN element.
0271: *
0272: * @return the newly-created element
0273: */
0274: public static Element createSpan() {
0275: return impl.createElement("span");
0276: }
0277:
0278: /**
0279: * Creates an HTML TABLE element.
0280: *
0281: * @return the newly-created element
0282: */
0283: public static Element createTable() {
0284: return impl.createElement("table");
0285: }
0286:
0287: /**
0288: * Creates an HTML TBODY element.
0289: *
0290: * @return the newly-created element
0291: */
0292: public static Element createTBody() {
0293: return impl.createElement("tbody");
0294: }
0295:
0296: /**
0297: * Creates an HTML TD element.
0298: *
0299: * @return the newly-created element
0300: */
0301: public static Element createTD() {
0302: return impl.createElement("td");
0303: }
0304:
0305: /**
0306: * Creates an HTML TEXTAREA element.
0307: *
0308: * @return the newly-created element
0309: */
0310: public static Element createTextArea() {
0311: return impl.createElement("textarea");
0312: }
0313:
0314: /**
0315: * Creates an HTML TFOOT element.
0316: *
0317: * @return the newly-created element
0318: */
0319: public static Element createTFoot() {
0320: return impl.createElement("tfoot");
0321: }
0322:
0323: /**
0324: * Creates an HTML TH element.
0325: *
0326: * @return the newly-created element
0327: */
0328: public static Element createTH() {
0329: return impl.createElement("th");
0330: }
0331:
0332: /**
0333: * Creates an HTML THEAD element.
0334: *
0335: * @return the newly-created element
0336: */
0337: public static Element createTHead() {
0338: return impl.createElement("thead");
0339: }
0340:
0341: /**
0342: * Creates an HTML TR element.
0343: *
0344: * @return the newly-created element
0345: */
0346: public static Element createTR() {
0347: return impl.createElement("tr");
0348: }
0349:
0350: /**
0351: * Cancels bubbling for the given event. This will stop the event from being
0352: * propagated to parent elements.
0353: *
0354: * @param evt the event on which to cancel bubbling
0355: * @param cancel <code>true</code> to cancel bubbling
0356: */
0357: public static void eventCancelBubble(Event evt, boolean cancel) {
0358: impl.eventCancelBubble(evt, cancel);
0359: }
0360:
0361: /**
0362: * Gets whether the ALT key was depressed when the given event occurred.
0363: *
0364: * @param evt the event to be tested
0365: * @return <code>true</code> if ALT was depressed when the event occurred
0366: */
0367: public static boolean eventGetAltKey(Event evt) {
0368: return impl.eventGetAltKey(evt);
0369: }
0370:
0371: /**
0372: * Gets the mouse buttons that were depressed when the given event occurred.
0373: *
0374: * @param evt the event to be tested
0375: * @return a bit-field, defined by {@link Event#BUTTON_LEFT},
0376: * {@link Event#BUTTON_MIDDLE}, and {@link Event#BUTTON_RIGHT}
0377: */
0378: public static int eventGetButton(Event evt) {
0379: return impl.eventGetButton(evt);
0380: }
0381:
0382: /**
0383: * Gets the mouse x-position within the browser window's client area.
0384: *
0385: * @param evt the event to be tested
0386: * @return the mouse x-position
0387: */
0388: public static int eventGetClientX(Event evt) {
0389: return impl.eventGetClientX(evt);
0390: }
0391:
0392: /**
0393: * Gets the mouse y-position within the browser window's client area.
0394: *
0395: * @param evt the event to be tested
0396: * @return the mouse y-position
0397: */
0398: public static int eventGetClientY(Event evt) {
0399: return impl.eventGetClientY(evt);
0400: }
0401:
0402: /**
0403: * Gets whether the CTRL key was depressed when the given event occurred.
0404: *
0405: * @param evt the event to be tested
0406: * @return <code>true</code> if CTRL was depressed when the event occurred
0407: */
0408: public static boolean eventGetCtrlKey(Event evt) {
0409: return impl.eventGetCtrlKey(evt);
0410: }
0411:
0412: /**
0413: * Gets the current event that is being fired. The current event is only
0414: * available within the lifetime of the onBrowserEvent function. Once the
0415: * onBrowserEvent method returns, the current event is reset to null.
0416: *
0417: * @return the current event
0418: */
0419: public static Event eventGetCurrentEvent() {
0420: return currentEvent;
0421: }
0422:
0423: /**
0424: * Gets the current target element of the given event. This is the element
0425: * whose listener fired last, not the element which fired the event initially.
0426: *
0427: * @param evt the event
0428: * @return the event's current target element
0429: * @see DOM#eventGetTarget(Event)
0430: */
0431: public static Element eventGetCurrentTarget(Event evt) {
0432: return impl.eventGetCurrentTarget(evt);
0433: }
0434:
0435: /**
0436: * Gets the element from which the mouse pointer was moved (only valid for
0437: * {@link Event#ONMOUSEOVER}).
0438: *
0439: * @param evt the event to be tested
0440: * @return the element from which the mouse pointer was moved
0441: */
0442: public static Element eventGetFromElement(Event evt) {
0443: return impl.eventGetFromElement(evt);
0444: }
0445:
0446: /**
0447: * Gets the key code associated with this event.
0448: *
0449: * <p>
0450: * For {@link Event#ONKEYPRESS}, this method returns the Unicode value of the
0451: * character generated. For {@link Event#ONKEYDOWN} and {@link Event#ONKEYUP},
0452: * it returns the code associated with the physical key.
0453: * </p>
0454: *
0455: * @param evt the event to be tested
0456: * @return the Unicode character or key code.
0457: * @see com.google.gwt.user.client.ui.KeyboardListener
0458: */
0459: public static int eventGetKeyCode(Event evt) {
0460: return impl.eventGetKeyCode(evt);
0461: }
0462:
0463: /**
0464: * Gets whether the META key was depressed when the given event occurred.
0465: *
0466: * @param evt the event to be tested
0467: * @return <code>true</code> if META was depressed when the event occurred
0468: */
0469: public static boolean eventGetMetaKey(Event evt) {
0470: return impl.eventGetMetaKey(evt);
0471: }
0472:
0473: /**
0474: * Gets the velocity of the mouse wheel associated with the event along the Y
0475: * axis.
0476: * <p>
0477: * The velocity of the event is an artifical measurement for relative
0478: * comparisons of wheel activity. It is affected by some non-browser factors,
0479: * including choice of input hardware and mouse acceleration settings. The
0480: * sign of the velocity measurement agrees with the screen coordinate system;
0481: * negative values are towards the origin and positive values are away from
0482: * the origin. Standard scrolling speed is approximately ten units per event.
0483: * </p>
0484: *
0485: * @param evt the event to be examined.
0486: * @return The velocity of the mouse wheel.
0487: */
0488: public static int eventGetMouseWheelVelocityY(Event evt) {
0489: return impl.eventGetMouseWheelVelocityY(evt);
0490: }
0491:
0492: /**
0493: * Gets the key-repeat state of this event.
0494: *
0495: * @param evt the event to be tested
0496: * @return <code>true</code> if this key event was an auto-repeat
0497: */
0498: public static boolean eventGetRepeat(Event evt) {
0499: return impl.eventGetRepeat(evt);
0500: }
0501:
0502: /**
0503: * Gets the mouse x-position on the user's display.
0504: *
0505: * @param evt the event to be tested
0506: * @return the mouse x-position
0507: */
0508: public static int eventGetScreenX(Event evt) {
0509: return impl.eventGetScreenX(evt);
0510: }
0511:
0512: /**
0513: * Gets the mouse y-position on the user's display.
0514: *
0515: * @param evt the event to be tested
0516: * @return the mouse y-position
0517: */
0518: public static int eventGetScreenY(Event evt) {
0519: return impl.eventGetScreenY(evt);
0520: }
0521:
0522: /**
0523: * Gets whether the shift key was depressed when the given event occurred.
0524: *
0525: * @param evt the event to be tested
0526: * @return <code>true</code> if shift was depressed when the event occurred
0527: */
0528: public static boolean eventGetShiftKey(Event evt) {
0529: return impl.eventGetShiftKey(evt);
0530: }
0531:
0532: /**
0533: * Returns the element that was the actual target of the given event.
0534: *
0535: * @param evt the event to be tested
0536: * @return the target element
0537: */
0538: public static Element eventGetTarget(Event evt) {
0539: return impl.eventGetTarget(evt);
0540: }
0541:
0542: /**
0543: * Gets the element to which the mouse pointer was moved (only valid for
0544: * {@link Event#ONMOUSEOUT}).
0545: *
0546: * @param evt the event to be tested
0547: * @return the element to which the mouse pointer was moved
0548: */
0549: public static Element eventGetToElement(Event evt) {
0550: return impl.eventGetToElement(evt);
0551: }
0552:
0553: /**
0554: * Gets the enumerated type of this event (as defined in {@link Event}).
0555: *
0556: * @param evt the event to be tested
0557: * @return the event's enumerated type
0558: */
0559: public static int eventGetType(Event evt) {
0560: return impl.eventGetTypeInt(evt);
0561: }
0562:
0563: /**
0564: * Gets the type of the given event as a string.
0565: *
0566: * @param evt the event to be tested
0567: * @return the event's type name
0568: */
0569: public static String eventGetTypeString(Event evt) {
0570: return impl.eventGetType(evt);
0571: }
0572:
0573: /**
0574: * Prevents the browser from taking its default action for the given event.
0575: *
0576: * @param evt the event whose default action is to be prevented
0577: */
0578: public static void eventPreventDefault(Event evt) {
0579: impl.eventPreventDefault(evt);
0580: }
0581:
0582: /**
0583: * Sets the key code associated with the given keyboard event.
0584: *
0585: * @param evt the event whose key code is to be set
0586: * @param key the new key code
0587: */
0588: public static void eventSetKeyCode(Event evt, char key) {
0589: impl.eventSetKeyCode(evt, key);
0590: }
0591:
0592: /**
0593: * Returns a stringized version of the event. This string is for debugging
0594: * purposes and will NOT be consistent on different browsers.
0595: *
0596: * @param evt the event to stringize
0597: * @return a string form of the event
0598: */
0599: public static String eventToString(Event evt) {
0600: return impl.eventToString(evt);
0601: }
0602:
0603: /**
0604: * Gets an element's absolute left coordinate in the document's coordinate
0605: * system.
0606: *
0607: * @param elem the element to be measured
0608: * @return the element's absolute left coordinate
0609: */
0610: public static int getAbsoluteLeft(Element elem) {
0611: return impl.getAbsoluteLeft(elem);
0612: }
0613:
0614: /**
0615: * Gets an element's absolute top coordinate in the document's coordinate
0616: * system.
0617: *
0618: * @param elem the element to be measured
0619: * @return the element's absolute top coordinate
0620: */
0621: public static int getAbsoluteTop(Element elem) {
0622: return impl.getAbsoluteTop(elem);
0623: }
0624:
0625: /**
0626: * Gets any named attribute from an element, as a string.
0627: *
0628: * @param elem the element whose attribute is to be retrieved
0629: * @param attr the name of the attribute
0630: * @return the attribute's value
0631: * @deprecated Use the more appropriately named
0632: * {@link #getElementProperty(Element, String)} instead.
0633: */
0634: @Deprecated
0635: public static String getAttribute(Element elem, String attr) {
0636: return getElementProperty(elem, attr);
0637: }
0638:
0639: /**
0640: * Gets a boolean attribute on the given element.
0641: *
0642: * @param elem the element whose attribute is to be set
0643: * @param attr the name of the attribute to be set
0644: * @return the attribute's value as a boolean
0645: * @deprecated Use the more appropriately named
0646: * {@link #getElementPropertyBoolean(Element, String)} instead.
0647: */
0648: @Deprecated
0649: public static boolean getBooleanAttribute(Element elem, String attr) {
0650: return getElementPropertyBoolean(elem, attr);
0651: }
0652:
0653: /**
0654: * Gets the element that currently has mouse capture.
0655: *
0656: * @return a handle to the capture element, or <code>null</code> if none
0657: * exists
0658: */
0659: public static Element getCaptureElement() {
0660: return sCaptureElem;
0661: }
0662:
0663: /**
0664: * Gets an element's n-th child element.
0665: *
0666: * @param parent the element whose child is to be retrieved
0667: * @param index the index of the child element
0668: * @return the n-th child element
0669: */
0670: public static Element getChild(Element parent, int index) {
0671: return impl.getChild(parent, index);
0672: }
0673:
0674: /**
0675: * Gets the number of child elements present in a given parent element.
0676: *
0677: * @param parent the element whose children are to be counted
0678: * @return the number of children
0679: */
0680: public static int getChildCount(Element parent) {
0681: return impl.getChildCount(parent);
0682: }
0683:
0684: /**
0685: * Gets the index of a given child element within its parent.
0686: *
0687: * @param parent the parent element
0688: * @param child the child element
0689: * @return the child's index within its parent, or <code>-1</code> if it is
0690: * not a child of the given parent
0691: */
0692: public static int getChildIndex(Element parent, Element child) {
0693: return impl.getChildIndex(parent, child);
0694: }
0695:
0696: /**
0697: * Gets the named attribute from the element.
0698: *
0699: * @param elem the element whose property is to be retrieved
0700: * @param attr the name of the attribute
0701: * @return the value of the attribute
0702: */
0703: public static String getElementAttribute(Element elem, String attr) {
0704: return impl.getElementAttribute(elem, attr);
0705: }
0706:
0707: /**
0708: * Gets the element associated with the given unique id within the entire
0709: * document.
0710: *
0711: * @param id the id whose associated element is to be retrieved
0712: * @return the associated element, or <code>null</code> if none is found
0713: */
0714: public static Element getElementById(String id) {
0715: return impl.getElementById(id);
0716: }
0717:
0718: /**
0719: * Gets any named property from an element, as a string.
0720: *
0721: * @param elem the element whose property is to be retrieved
0722: * @param prop the name of the property
0723: * @return the property's value
0724: */
0725: public static String getElementProperty(Element elem, String prop) {
0726: return impl.getElementProperty(elem, prop);
0727: }
0728:
0729: /**
0730: * Gets any named property from an element, as a boolean.
0731: *
0732: * @param elem the element whose property is to be retrieved
0733: * @param prop the name of the property
0734: * @return the property's value as a boolean
0735: */
0736: public static boolean getElementPropertyBoolean(Element elem,
0737: String prop) {
0738: return impl.getElementPropertyBoolean(elem, prop);
0739: }
0740:
0741: /**
0742: * Gets any named property from an element, as an int.
0743: *
0744: * @param elem the element whose property is to be retrieved
0745: * @param prop the name of the property
0746: * @return the property's value as an int
0747: */
0748: public static int getElementPropertyInt(Element elem, String prop) {
0749: return impl.getElementPropertyInt(elem, prop);
0750: }
0751:
0752: /**
0753: * Gets the current set of events sunk by a given element.
0754: *
0755: * @param elem the element whose events are to be retrieved
0756: * @return a bitfield describing the events sunk on this element (its possible
0757: * values are described in {@link Event})
0758: */
0759: public static int getEventsSunk(Element elem) {
0760: return impl.getEventsSunk(elem);
0761: }
0762:
0763: /**
0764: * Gets the first child element of the given element.
0765: *
0766: * @param elem the element whose child is to be retrieved
0767: * @return the child element
0768: */
0769: public static Element getFirstChild(Element elem) {
0770: return impl.getFirstChild(elem);
0771: }
0772:
0773: /**
0774: * Gets the src attribute of an img element. This method is paired with
0775: * {@link #setImgSrc(Element, String)} so that it always returns the correct
0776: * url.
0777: *
0778: * @param img a non-null img whose src attribute is to be read.
0779: * @return the src url of the img
0780: */
0781: public static String getImgSrc(Element img) {
0782: return impl.getImgSrc(img);
0783: }
0784:
0785: /**
0786: * Gets an HTML representation of an element's children.
0787: *
0788: * @param elem the element whose HTML is to be retrieved
0789: * @return the HTML representation of the element's children
0790: */
0791: public static String getInnerHTML(Element elem) {
0792: return impl.getInnerHTML(elem);
0793: }
0794:
0795: /**
0796: * Gets the text contained within an element. If the element has child
0797: * elements, only the text between them will be retrieved.
0798: *
0799: * @param elem the element whose inner text is to be retrieved
0800: * @return the text inside this element
0801: */
0802: public static String getInnerText(Element elem) {
0803: return impl.getInnerText(elem);
0804: }
0805:
0806: /**
0807: * Gets an integer attribute on a given element.
0808: *
0809: * @param elem the element whose attribute is to be retrieved
0810: * @param attr the name of the attribute to be retrieved
0811: * @return the attribute's value as an integer
0812: * @deprecated Use the more appropriately named
0813: * {@link #getElementPropertyInt(Element, String)} instead.
0814: */
0815: @Deprecated
0816: public static int getIntAttribute(Element elem, String attr) {
0817: return getElementPropertyInt(elem, attr);
0818: }
0819:
0820: /**
0821: * Gets an integer attribute on a given element's style.
0822: *
0823: * @param elem the element whose style attribute is to be retrieved
0824: * @param attr the name of the attribute to be retrieved
0825: * @return the style attribute's value as an integer
0826: */
0827: public static int getIntStyleAttribute(Element elem, String attr) {
0828: return impl.getIntStyleAttribute(elem, attr);
0829: }
0830:
0831: /**
0832: * Gets an element's next sibling element.
0833: *
0834: * @param elem the element whose sibling is to be retrieved
0835: * @return the sibling element
0836: */
0837: public static Element getNextSibling(Element elem) {
0838: return impl.getNextSibling(elem);
0839: }
0840:
0841: /**
0842: * Gets an element's parent element.
0843: *
0844: * @param elem the element whose parent is to be retrieved
0845: * @return the parent element
0846: */
0847: public static Element getParent(Element elem) {
0848: return impl.getParent(elem);
0849: }
0850:
0851: /**
0852: * Gets an attribute of the given element's style.
0853: *
0854: * @param elem the element whose style attribute is to be retrieved
0855: * @param attr the name of the style attribute to be retrieved
0856: * @return the style attribute's value
0857: */
0858: public static String getStyleAttribute(Element elem, String attr) {
0859: return impl.getStyleAttribute(elem, attr);
0860: }
0861:
0862: /**
0863: * Inserts an element as a child of the given parent element, before another
0864: * child of that parent.
0865: *
0866: * @param parent the parent element
0867: * @param child the child element to add to <code>parent</code>
0868: * @param before an existing child element of <code>parent</code> before
0869: * which <code>child</code> will be inserted
0870: */
0871: public static void insertBefore(Element parent, Element child,
0872: Element before) {
0873: impl.insertBefore(parent, child, before);
0874: }
0875:
0876: /**
0877: * Inserts an element as a child of the given parent element.
0878: *
0879: * @param parent the parent element
0880: * @param child the child element to add to <code>parent</code>
0881: * @param index the index before which the child will be inserted (any value
0882: * greater than the number of existing children will cause the child
0883: * to be appended)
0884: */
0885: public static void insertChild(Element parent, Element child,
0886: int index) {
0887: impl.insertChild(parent, child, index);
0888: }
0889:
0890: /**
0891: * Creates an <code><option></code> element and inserts it as a child
0892: * of the specified <code><select></code> element. If the index is
0893: * less than zero, or greater than or equal to the length of the list, then
0894: * the option element will be appended to the end of the list.
0895: *
0896: * @param select the <code><select></code> element
0897: * @param item the text of the new item; cannot be <code>null</code>
0898: * @param value the <code>value</code> attribute for the new
0899: * <code><option></code>; cannot be <code>null</code>
0900: * @param index the index at which to insert the child
0901: */
0902: public static void insertListItem(Element select, String item,
0903: String value, int index) {
0904: impl.insertListItem(select, item, value, index);
0905: }
0906:
0907: /**
0908: * Determine whether one element is equal to, or the child of, another.
0909: *
0910: * @param parent the potential parent element
0911: * @param child the potential child element
0912: * @return <code>true</code> if the relationship holds
0913: * @see #compare(Element, Element)
0914: */
0915: public static boolean isOrHasChild(Element parent, Element child) {
0916: return impl.isOrHasChild(parent, child);
0917: }
0918:
0919: /**
0920: * Releases mouse capture on the given element. Calling this method has no
0921: * effect if the element does not currently have mouse capture.
0922: *
0923: * @param elem the element to release capture
0924: * @see #setCapture(Element)
0925: */
0926: public static void releaseCapture(Element elem) {
0927: if ((sCaptureElem != null) && compare(elem, sCaptureElem)) {
0928: sCaptureElem = null;
0929: }
0930: impl.releaseCapture(elem);
0931: }
0932:
0933: /**
0934: * Removes a child element from the given parent element.
0935: *
0936: * @param parent the parent element
0937: * @param child the child element to be removed
0938: */
0939: public static void removeChild(Element parent, Element child) {
0940: impl.removeChild(parent, child);
0941: }
0942:
0943: /**
0944: * Removes the named attribute from the given element.
0945: *
0946: * @param elem the element whose attribute is to be removed
0947: * @param attr the name of the element to remove
0948: */
0949: public static void removeElementAttribute(Element elem, String attr) {
0950: impl.removeElementAttribute(elem, attr);
0951: }
0952:
0953: /**
0954: * Removes an element from the preview stack. This element will no longer
0955: * capture events, though any preview underneath it will begin to do so.
0956: *
0957: * @param preview the event preview to be removed from the stack
0958: */
0959: public static void removeEventPreview(EventPreview preview) {
0960: // Remove the event preview from the stack. If it was on top,
0961: // any preview underneath it will automatically begin to
0962: // receive events.
0963: if (sEventPreviewStack != null) {
0964: sEventPreviewStack.remove(preview);
0965: }
0966: }
0967:
0968: /**
0969: * Scrolls the given element into view.
0970: *
0971: * <p>
0972: * This method crawls up the DOM hierarchy, adjusting the scrollLeft and
0973: * scrollTop properties of each scrollable element to ensure that the
0974: * specified element is completely in view. It adjusts each scroll position by
0975: * the minimum amount necessary.
0976: * </p>
0977: *
0978: * @param elem the element to be made visible
0979: */
0980: public static void scrollIntoView(Element elem) {
0981: impl.scrollIntoView(elem);
0982: }
0983:
0984: /**
0985: * Sets an attribute on the given element.
0986: *
0987: * @param elem the element whose attribute is to be set
0988: * @param attr the name of the attribute to be set
0989: * @param value the new attribute value
0990: * @deprecated Use the more appropriately named
0991: * {@link #setElementProperty(Element, String, String)} instead.
0992: */
0993: @Deprecated
0994: public static void setAttribute(Element elem, String attr,
0995: String value) {
0996: setElementProperty(elem, attr, value);
0997: }
0998:
0999: /**
1000: * Sets a boolean attribute on the given element.
1001: *
1002: * @param elem the element whose attribute is to be set
1003: * @param attr the name of the attribute to be set
1004: * @param value the attribute's new boolean value
1005: * @deprecated Use the more appropriately named
1006: * {@link #setElementPropertyBoolean(Element, String, boolean)}
1007: * instead.
1008: */
1009: @Deprecated
1010: public static void setBooleanAttribute(Element elem, String attr,
1011: boolean value) {
1012: setElementPropertyBoolean(elem, attr, value);
1013: }
1014:
1015: /**
1016: * Sets mouse-capture on the given element. This element will directly receive
1017: * all mouse events until {@link #releaseCapture(Element)} is called on it.
1018: *
1019: * @param elem the element on which to set mouse capture
1020: */
1021: public static void setCapture(Element elem) {
1022: sCaptureElem = elem;
1023: impl.setCapture(elem);
1024: }
1025:
1026: /**
1027: * Sets an attribute on a given element.
1028: *
1029: * @param elem element whose attribute is to be set
1030: * @param attr the name of the attribute
1031: * @param value the value to which the attribute should be set
1032: */
1033: public static void setElementAttribute(Element elem, String attr,
1034: String value) {
1035: impl.setElementAttribute(elem, attr, value);
1036: }
1037:
1038: /**
1039: * Sets a property on the given element.
1040: *
1041: * @param elem the element whose property is to be set
1042: * @param prop the name of the property to be set
1043: * @param value the new property value
1044: */
1045: public static void setElementProperty(Element elem, String prop,
1046: String value) {
1047: impl.setElementProperty(elem, prop, value);
1048: }
1049:
1050: /**
1051: * Sets a boolean property on the given element.
1052: *
1053: * @param elem the element whose property is to be set
1054: * @param prop the name of the property to be set
1055: * @param value the new property value as a boolean
1056: */
1057: public static void setElementPropertyBoolean(Element elem,
1058: String prop, boolean value) {
1059: impl.setElementPropertyBoolean(elem, prop, value);
1060: }
1061:
1062: /**
1063: * Sets an int property on the given element.
1064: *
1065: * @param elem the element whose property is to be set
1066: * @param prop the name of the property to be set
1067: * @param value the new property value as an int
1068: */
1069: public static void setElementPropertyInt(Element elem, String prop,
1070: int value) {
1071: impl.setElementPropertyInt(elem, prop, value);
1072: }
1073:
1074: /**
1075: * Sets the {@link EventListener} to receive events for the given element.
1076: * Only one such listener may exist for a single element.
1077: *
1078: * @param elem the element whose listener is to be set
1079: * @param listener the listener to receive {@link Event events}
1080: */
1081: public static void setEventListener(Element elem,
1082: EventListener listener) {
1083: impl.setEventListener(elem, listener);
1084: }
1085:
1086: /**
1087: * Sets the src attribute of an img element. This method ensures that imgs
1088: * only ever have their contents requested one single time from the server.
1089: *
1090: * @param img a non-null img whose src attribute will be set.
1091: * @param src a non-null url for the img
1092: */
1093: public static void setImgSrc(Element img, String src) {
1094: impl.setImgSrc(img, src);
1095: }
1096:
1097: /**
1098: * Sets the HTML contained within an element.
1099: *
1100: * @param elem the element whose inner HTML is to be set
1101: * @param html the new html
1102: */
1103: public static void setInnerHTML(Element elem, String html) {
1104: impl.setInnerHTML(elem, html);
1105: }
1106:
1107: /**
1108: * Sets the text contained within an element. If the element already has
1109: * children, they will be destroyed.
1110: *
1111: * @param elem the element whose inner text is to be set
1112: * @param text the new text
1113: */
1114: public static void setInnerText(Element elem, String text) {
1115: impl.setInnerText(elem, text);
1116: }
1117:
1118: /**
1119: * Sets an integer attribute on the given element.
1120: *
1121: * @param elem the element whose attribute is to be set
1122: * @param attr the name of the attribute to be set
1123: * @param value the attribute's new integer value
1124: * @deprecated Use the more appropriately named
1125: * {@link #setElementPropertyInt(Element, String, int)} instead.
1126: */
1127: @Deprecated
1128: public static void setIntAttribute(Element elem, String attr,
1129: int value) {
1130: setElementPropertyInt(elem, attr, value);
1131: }
1132:
1133: /**
1134: * Sets an integer attribute on the given element's style.
1135: *
1136: * @param elem the element whose style attribute is to be set
1137: * @param attr the name of the style attribute to be set
1138: * @param value the style attribute's new integer value
1139: */
1140: public static void setIntStyleAttribute(Element elem, String attr,
1141: int value) {
1142: impl.setIntStyleAttribute(elem, attr, value);
1143: }
1144:
1145: /**
1146: * Sets the option text of the given select object.
1147: *
1148: * @param select the select object whose option text is being set
1149: * @param text the text to set
1150: * @param index the index of the option whose text should be set
1151: */
1152: public static void setOptionText(Element select, String text,
1153: int index) {
1154: impl.setOptionText(select, text, index);
1155: }
1156:
1157: /**
1158: * Sets an attribute on the given element's style.
1159: *
1160: * @param elem the element whose style attribute is to be set
1161: * @param attr the name of the style attribute to be set
1162: * @param value the style attribute's new value
1163: */
1164: public static void setStyleAttribute(Element elem, String attr,
1165: String value) {
1166: impl.setStyleAttribute(elem, attr, value);
1167: }
1168:
1169: /**
1170: * Sets the current set of events sunk by a given element. These events will
1171: * be fired to the nearest {@link EventListener} specified on any of the
1172: * element's parents.
1173: *
1174: * @param elem the element whose events are to be retrieved
1175: * @param eventBits a bitfield describing the events sunk on this element (its
1176: * possible values are described in {@link Event})
1177: */
1178: public static void sinkEvents(Element elem, int eventBits) {
1179: impl.sinkEvents(elem, eventBits);
1180: }
1181:
1182: /**
1183: * Returns a stringized version of the element. This string is for debugging
1184: * purposes and will NOT be consistent on different browsers.
1185: *
1186: * @param elem the element to stringize
1187: * @return a string form of the element
1188: */
1189: public static String toString(Element elem) {
1190: return impl.toString(elem);
1191: }
1192:
1193: /**
1194: * Gets the height of the browser window's client area excluding the scroll
1195: * bar.
1196: *
1197: * @return the window's client height
1198: */
1199: public static int windowGetClientHeight() {
1200: return impl.windowGetClientHeight();
1201: }
1202:
1203: /**
1204: * Gets the width of the browser window's client area excluding the vertical
1205: * scroll bar.
1206: *
1207: * @return the window's client width
1208: */
1209: public static int windowGetClientWidth() {
1210: return impl.windowGetClientWidth();
1211: }
1212:
1213: /**
1214: * This method is called directly by native code when any event is fired.
1215: *
1216: * @param evt the handle to the event being fired.
1217: * @param elem the handle to the element that received the event.
1218: * @param listener the listener associated with the element that received the
1219: * event.
1220: */
1221: static void dispatchEvent(Event evt, Element elem,
1222: EventListener listener) {
1223: UncaughtExceptionHandler handler = GWT
1224: .getUncaughtExceptionHandler();
1225: if (handler != null) {
1226: dispatchEventAndCatch(evt, elem, listener, handler);
1227: } else {
1228: dispatchEventImpl(evt, elem, listener);
1229: }
1230: }
1231:
1232: /**
1233: * This method is called directly by native code when event preview is being
1234: * used.
1235: *
1236: * @param evt a handle to the event being previewed
1237: * @return <code>false</code> to cancel the event
1238: */
1239: static boolean previewEvent(Event evt) {
1240: // If event previews are present, redirect events to the topmost of them.
1241: boolean ret = true;
1242: if (sEventPreviewStack != null && sEventPreviewStack.size() > 0) {
1243: EventPreview preview = sEventPreviewStack
1244: .get(sEventPreviewStack.size() - 1);
1245: if (!(ret = preview.onEventPreview(evt))) {
1246: // If the preview cancels the event, stop it from bubbling and
1247: // performing its default action.
1248: eventCancelBubble(evt, true);
1249: eventPreventDefault(evt);
1250: }
1251: }
1252:
1253: return ret;
1254: }
1255:
1256: private static void dispatchEventAndCatch(Event evt, Element elem,
1257: EventListener listener, UncaughtExceptionHandler handler) {
1258: try {
1259: dispatchEventImpl(evt, elem, listener);
1260: } catch (Throwable e) {
1261: handler.onUncaughtException(e);
1262: }
1263: }
1264:
1265: private static void dispatchEventImpl(Event evt, Element elem,
1266: EventListener listener) {
1267: // If this element has capture...
1268: if (elem == sCaptureElem) {
1269: // ... and it's losing capture, clear sCaptureElem.
1270: if (eventGetType(evt) == Event.ONLOSECAPTURE) {
1271: sCaptureElem = null;
1272: }
1273: }
1274:
1275: // Preserve the current event in case we are in a reentrant event dispatch.
1276: Event prevCurrentEvent = currentEvent;
1277: currentEvent = evt;
1278: try {
1279: // Pass the event to the listener.
1280: listener.onBrowserEvent(evt);
1281: } finally {
1282: currentEvent = prevCurrentEvent;
1283: }
1284: }
1285: }
|