Java > Open Source Codes > com > google > gwt > user > client > DOM


1 /*
2  * Copyright 2007 Google Inc.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5  * use this file except in compliance with the License. You may obtain a copy of
6  * the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13  * License for the specific language governing permissions and limitations under
14  * the License.
15  */
16 package com.google.gwt.user.client;
17
18 import com.google.gwt.core.client.GWT;
19 import com.google.gwt.core.client.GWT.UncaughtExceptionHandler;
20 import com.google.gwt.user.client.impl.DOMImpl;
21
22 import java.util.ArrayList ;
23
24 /**
25  * This class provides a set of static methods that allow you to manipulate the
26  * browser's Document Object Model (DOM). It contains methods for manipulating
27  * both {@link com.google.gwt.user.client.Element elements} and
28  * {@link com.google.gwt.user.client.Event events}.
29  */
30 public class DOM {
31
32   private static DOMImpl impl;
33   private static Element sCaptureElem;
34
35   //<BrowserEventPreview>
36 private static ArrayList sEventPreviewStack = new ArrayList ();
37
38   static {
39     impl = (DOMImpl) GWT.create(DOMImpl.class);
40     impl.init();
41   }
42
43   /**
44    * Adds an event preview to the preview stack. As long as this preview remains
45    * on the top of the stack, it will receive all events before they are fired
46    * to their listeners. Note that the event preview will receive <u>all </u>
47    * events, including those received due to bubbling, whereas normal event
48    * handlers only receive explicitly sunk events.
49    *
50    * @param preview the event preview to be added to the stack.
51    */
52   public static void addEventPreview(EventPreview preview) {
53     // Add the event preview to the stack. It will automatically
54 // begin receiving events.
55 sEventPreviewStack.add(preview);
56   }
57
58   /**
59    * Appends one element to another's list of children.
60    *
61    * @param parent the parent element
62    * @param child its new child
63    */
64   public static void appendChild(Element parent, Element child) {
65     impl.appendChild(parent, child);
66   }
67
68   /**
69    * Compares two elements for equality (note that reference equality is not
70    * sufficient to determine equality among elements on most browsers).
71    *
72    * @param elem1 the first element to be compared
73    * @param elem2 the second element to be compared
74    * @return <code>true</code> if they are in fact the same element
75    * @see #isOrHasChild(Element, Element)
76    */
77   public static boolean compare(Element elem1, Element elem2) {
78     return impl.compare(elem1, elem2);
79   }
80
81   /**
82    * Creates an HTML A element.
83    *
84    * @return the newly-created element
85    */
86   public static Element createAnchor() {
87     return impl.createElement("A");
88   }
89
90   /**
91    * Creates an HTML BUTTON element.
92    *
93    * @return the newly-created element
94    */
95   public static Element createButton() {
96     return impl.createElement("button");
97   }
98
99   /**
100    * Creates an HTML CAPTION element.
101    *
102    * @return the newly-created element
103    */
104   public static Element createCaption() {
105     return impl.createElement("caption");
106   }
107
108   /**
109    * Creates an HTML COL element.
110    *
111    * @return the newly-created element
112    */
113   public static Element createCol() {
114     return impl.createElement("col");
115   }
116
117   /**
118    * Creates an HTML COLGROUP element.
119    *
120    * @return the newly-created element
121    */
122   public static Element createColGroup() {
123     return impl.createElement("colgroup");
124   }
125
126   /**
127    * Creates an HTML DIV element.
128    *
129    * @return the newly-created element
130    */
131   public static Element createDiv() {
132     return impl.createElement("div");
133   }
134
135   /**
136    * Creates an HTML element.
137    *
138    * @param tagName the HTML tag of the element to be created
139    * @return the newly-created element
140    */
141   public static Element createElement(String tagName) {
142     return impl.createElement(tagName);
143   }
144
145   /**
146    * Creates an HTML FIELDSET element.
147    *
148    * @return the newly-created element
149    */
150   public static Element createFieldSet() {
151     return impl.createElement("fieldset");
152   }
153
154   /**
155    * Creates an HTML FORM element.
156    *
157    * @return the newly-created element
158    */
159   public static Element createForm() {
160     return impl.createElement("form");
161   }
162
163   /**
164    * Creates an HTML IFRAME element.
165    *
166    * @return the newly-created element
167    */
168   public static Element createIFrame() {
169     return impl.createElement("iframe");
170   }
171
172   /**
173    * Creates an HTML IMG element.
174    *
175    * @return the newly-created element
176    */
177   public static Element createImg() {
178     return impl.createElement("img");
179   }
180
181   /**
182    * Creates an HTML INPUT type='CHECK' element.
183    *
184    * @return the newly-created element
185    */
186   public static Element createInputCheck() {
187     return impl.createInputElement("checkbox");
188   }
189
190   /**
191    * Creates an HTML INPUT type='PASSWORD' element.
192    *
193    * @return the newly-created element
194    */
195   public static Element createInputPassword() {
196     return impl.createInputElement("password");
197   }
198
199   /**
200    * Creates an HTML INPUT type='RADIO' element.
201    *
202    * @param group the name of the group with which this radio button will be
203    * associated
204    * @return the newly-created element
205    */
206   public static Element createInputRadio(String group) {
207     return impl.createInputRadioElement(group);
208   }
209
210   /**
211    * Creates an HTML INPUT type='TEXT' element.
212    *
213    * @return the newly-created element
214    */
215   public static Element createInputText() {
216     return impl.createInputElement("text");
217   }
218
219   /**
220    * Creates an HTML LABEL element.
221    *
222    * @return the newly-created element
223    */
224   public static Element createLabel() {
225     return impl.createElement("label");
226   }
227
228   /**
229    * Creates an HTML LEGEND element.
230    *
231    * @return the newly-created element
232    */
233   public static Element createLegend() {
234     return impl.createElement("legend");
235   }
236
237   /**
238    * Creates an HTML OPTIONS element.
239    *
240    * @return the newly-created element
241    */
242   public static Element createOptions() {
243     return impl.createElement("options");
244   }
245
246   /**
247    * Creates a single-selection HTML SELECT element. Equivalent to
248    * <pre>
249    * createSelect(false)
250    * </pre>
251    *
252    * @return the newly-created element
253    */
254   public static Element createSelect() {
255     return DOM.createSelect(false);
256   }
257
258   /**
259    * Creates an HTML SELECT element.
260    *
261    * @return the newly-created element
262    */
263   public static Element createSelect(boolean multiple) {
264     return impl.createSelectElement(multiple);
265   }
266
267   /**
268    * Creates an HTML SPAN element.
269    *
270    * @return the newly-created element
271    */
272   public static Element createSpan() {
273     return impl.createElement("span");
274   }
275
276   /**
277    * Creates an HTML TABLE element.
278    *
279    * @return the newly-created element
280    */
281   public static Element createTable() {
282     return impl.createElement("table");
283   }
284
285   /**
286    * Creates an HTML TBODY element.
287    *
288    * @return the newly-created element
289    */
290   public static Element createTBody() {
291     return impl.createElement("tbody");
292   }
293
294   /**
295    * Creates an HTML TD element.
296    *
297    * @return the newly-created element
298    */
299   public static Element createTD() {
300     return impl.createElement("td");
301   }
302
303   /**
304    * Creates an HTML TEXTAREA element.
305    *
306    * @return the newly-created element
307    */
308   public static Element createTextArea() {
309     return impl.createElement("textarea");
310   }
311
312   /**
313    * Creates an HTML TFOOT element.
314    *
315    * @return the newly-created element
316    */
317   public static Element createTFoot() {
318     return impl.createElement("tfoot");
319   }
320
321   /**
322    * Creates an HTML TH element.
323    *
324    * @return the newly-created element
325    */
326   public static Element createTH() {
327     return impl.createElement("th");
328   }
329
330   /**
331    * Creates an HTML THEAD element.
332    *
333    * @return the newly-created element
334    */
335   public static Element createTHead() {
336     return impl.createElement("thead");
337   }
338
339   /**
340    * Creates an HTML TR element.
341    *
342    * @return the newly-created element
343    */
344   public static Element createTR() {
345     return impl.createElement("tr");
346   }
347
348   /**
349    * Cancels bubbling for the given event. This will stop the event from being
350    * propagated to parent elements.
351    *
352    * @param evt the event on which to cancel bubbling
353    * @param cancel <code>true</code> to cancel bubbling
354    */
355   public static void eventCancelBubble(Event evt, boolean cancel) {
356     impl.eventCancelBubble(evt, cancel);
357   }
358
359   /**
360    * Gets whether the ALT key was depressed when the given event occurred.
361    *
362    * @param evt the event to be tested
363    * @return <code>true</code> if ALT was depressed when the event occurred
364    */
365   public static boolean eventGetAltKey(Event evt) {
366     return impl.eventGetAltKey(evt);
367   }
368
369   /**
370    * Gets the mouse buttons that were depressed when the given event occurred.
371    *
372    * @param evt the event to be tested
373    * @return a bit-field, defined by {@link Event#BUTTON_LEFT},
374    * {@link Event#BUTTON_MIDDLE}, and {@link Event#BUTTON_RIGHT}
375    */
376   public static int eventGetButton(Event evt) {
377     return impl.eventGetButton(evt);
378   }
379
380   /**
381    * Gets the mouse x-position within the browser window's client area.
382    *
383    * @param evt the event to be tested
384    * @return the mouse x-position
385    */
386   public static int eventGetClientX(Event evt) {
387     return impl.eventGetClientX(evt);
388   }
389
390   /**
391    * Gets the mouse y-position within the browser window's client area.
392    *
393    * @param evt the event to be tested
394    * @return the mouse y-position
395    */
396   public static int eventGetClientY(Event evt) {
397     return impl.eventGetClientY(evt);
398   }
399
400   /**
401    * Gets whether the CTRL key was depressed when the given event occurred.
402    *
403    * @param evt the event to be tested
404    * @return <code>true</code> if CTRL was depressed when the event occurred
405    */
406   public static boolean eventGetCtrlKey(Event evt) {
407     return impl.eventGetCtrlKey(evt);
408   }
409
410   /**
411    * Gets the element from which the mouse pointer was moved (only valid for
412    * {@link Event#ONMOUSEOVER}).
413    *
414    * @param evt the event to be tested
415    * @return the element from which the mouse pointer was moved
416    */
417   public static Element eventGetFromElement(Event evt) {
418     return impl.eventGetFromElement(evt);
419   }
420
421   /**
422    * Gets the key code associated with this event.
423    *
424    * <p>
425    * For {@link Event#ONKEYPRESS}, this method returns the Unicode value of the
426    * character generated. For {@link Event#ONKEYDOWN} and {@link Event#ONKEYUP},
427    * it returns the code associated with the physical key.
428    * </p>
429    *
430    * @param evt the event to be tested
431    * @return the Unicode character or key code.
432    * @see com.google.gwt.user.client.ui.KeyboardListener
433    */
434   public static int eventGetKeyCode(Event evt) {
435     return impl.eventGetKeyCode(evt);
436   }
437
438   /**
439    * Gets whether the META key was depressed when the given event occurred.
440    *
441    * @param evt the event to be tested
442    * @return <code>true</code> if META was depressed when the event occurred
443    */
444   public static boolean eventGetMetaKey(Event evt) {
445     return impl.eventGetMetaKey(evt);
446   }
447
448   /**
449    * Gets the velocity of the mouse wheel associated with the event along the
450    * Y axis.
451    * <p>
452    * The velocity of the event is an artifical measurement for relative
453    * comparisons of wheel activity. It is affected by some non-browser
454    * factors, including choice of input hardware and mouse acceleration
455    * settings. The sign of the velocity measurement agrees with the screen
456    * coordinate system; negative values are towards the origin and positive
457    * values are away from the origin. Standard scrolling speed is approximately
458    * ten units per event.
459    * </p>
460    *
461    * @param evt the event to be examined.
462    * @return The velocity of the mouse wheel.
463    */
464   public static int eventGetMouseWheelVelocityY(Event evt) {
465     return impl.eventGetMouseWheelVelocityY(evt);
466   }
467
468   /**
469    * Gets the key-repeat state of this event.
470    *
471    * @param evt the event to be tested
472    * @return <code>true</code> if this key event was an auto-repeat
473    */
474   public static boolean eventGetRepeat(Event evt) {
475     return impl.eventGetRepeat(evt);
476   }
477
478   /**
479    * Gets the mouse x-position on the user's display.
480    *
481    * @param evt the event to be tested
482    * @return the mouse x-position
483    */
484   public static int eventGetScreenX(Event evt) {
485     return impl.eventGetScreenX(evt);
486   }
487
488   /**
489    * Gets the mouse y-position on the user's display.
490    *
491    * @param evt the event to be tested
492    * @return the mouse y-position
493    */
494   public static int eventGetScreenY(Event evt) {
495     return impl.eventGetScreenY(evt);
496   }
497
498   /**
499    * Gets whether the shift key was depressed when the given event occurred.
500    *
501    * @param evt the event to be tested
502    * @return <code>true</code> if shift was depressed when the event occurred
503    */
504   public static boolean eventGetShiftKey(Event evt) {
505     return impl.eventGetShiftKey(evt);
506   }
507
508   /**
509    * Returns the element that was the actual target of the given event.
510    *
511    * @param evt the event to be tested
512    * @return the target element
513    */
514   public static Element eventGetTarget(Event evt) {
515     return impl.eventGetTarget(evt);
516   }
517
518   /**
519    * Gets the element to which the mouse pointer was moved (only valid for
520    * {@link Event#ONMOUSEOUT}).
521    *
522    * @param evt the event to be tested
523    * @return the element to which the mouse pointer was moved
524    */
525   public static Element eventGetToElement(Event evt) {
526     return impl.eventGetToElement(evt);
527   }
528
529   /**
530    * Gets the enumerated type of this event (as defined in {@link Event}).
531    *
532    * @param evt the event to be tested
533    * @return the event's enumerated type
534    */
535   public static int eventGetType(Event evt) {
536     return impl.eventGetTypeInt(evt);
537   }
538
539   /**
540    * Gets the type of the given event as a string.
541    *
542    * @param evt the event to be tested
543    * @return the event's type name
544    */
545   public static String eventGetTypeString(Event evt) {
546     return impl.eventGetType(evt);
547   }
548
549   /**
550    * Prevents the browser from taking its default action for the given event.
551    *
552    * @param evt the event whose default action is to be prevented
553    */
554   public static void eventPreventDefault(Event evt) {
555     impl.eventPreventDefault(evt);
556   }
557
558   /**
559    * Sets the key code associated with the given keyboard event.
560    *
561    * @param evt the event whose key code is to be set
562    * @param key the new key code
563    */
564   public static void eventSetKeyCode(Event evt, char key) {
565     impl.eventSetKeyCode(evt, key);
566   }
567
568   /**
569    * Returns a stringized version of the event. This string is for debugging
570    * purposes and will NOT be consistent on different browsers.
571    *
572    * @param evt the event to stringize
573    * @return a string form of the event
574    */
575   public static String eventToString(Event evt) {
576     return impl.eventToString(evt);
577   }
578
579   /**
580    * Gets an element's absolute left coordinate in the document's coordinate
581    * system.
582    *
583    * @param elem the element to be measured
584    * @return the element's absolute left coordinate
585    */
586   public static int getAbsoluteLeft(Element elem) {
587     return impl.getAbsoluteLeft(elem);
588   }
589
590   /**
591    * Gets an element's absolute top coordinate in the document's coordinate
592    * system.
593    *
594    * @param elem the element to be measured
595    * @return the element's absolute top coordinate
596    */
597   public static int getAbsoluteTop(Element elem) {
598     return impl.getAbsoluteTop(elem);
599   }
600
601   /**
602    * Gets any named attribute from an element, as a string.
603    *
604    * @param elem the element whose attribute is to be retrieved
605    * @param attr the name of the attribute
606    * @return the attribute's value
607    * @deprecated Use the more appropriately named
608    * {@link #getElementProperty(Element, String)} instead.
609    */
610   public static String getAttribute(Element elem, String attr) {
611     return getElementProperty(elem, attr);
612   }
613
614   /**
615    * Gets a boolean attribute on the given element.
616    *
617    * @param elem the element whose attribute is to be set
618    * @param attr the name of the attribute to be set
619    * @return the attribute's value as a boolean
620    * @deprecated Use the more appropriately named
621    * {@link #getElementPropertyBoolean(Element, String)} instead.
622    */
623   public static boolean getBooleanAttribute(Element elem, String attr) {
624     return getElementPropertyBoolean(elem, attr);
625   }
626
627   /**
628    * Gets the element that currently has mouse capture.
629    *
630    * @return a handle to the capture element, or <code>null</code> if none
631    * exists
632    */
633   public static Element getCaptureElement() {
634     return sCaptureElem;
635   }
636
637   /**
638    * Gets an element's n-th child element.
639    *
640    * @param parent the element whose child is to be retrieved
641    * @param index the index of the child element
642    * @return the n-th child element
643    */
644   public static Element getChild(Element parent, int index) {
645     return impl.getChild(parent, index);
646   }
647
648   /**
649    * Gets the number of child elements present in a given parent element.
650    *
651    * @param parent the element whose children are to be counted
652    * @return the number of children
653    */
654   public static int getChildCount(Element parent) {
655     return impl.getChildCount(parent);
656   }
657
658   /**
659    * Gets the index of a given child element within its parent.
660    *
661    * @param parent the parent element
662    * @param child the child element
663    * @return the child's index within its parent, or <code>-1</code> if it is
664    * not a child of the given parent
665    */
666   public static int getChildIndex(Element parent, Element child) {
667     return impl.getChildIndex(parent, child);
668   }
669
670   /**
671    * Gets the named attribute from the element.
672    *
673    * @param elem the element whose property is to be retrieved
674    * @param attr the name of the attribute
675    * @return the value of the attribute
676    */
677   public static String getElementAttribute(Element elem, String attr) {
678      return impl.getElementAttribute(elem, attr);
679   }
680
681   /**
682    * Gets the element associated with the given unique id within the entire
683    * document.
684    *
685    * @param id the id whose associated element is to be retrieved
686    * @return the associated element, or <code>null</code> if none is found
687    */
688   public static Element getElementById(String id) {
689     return impl.getElementById(id);
690   }
691   /**
692    * Gets any named property from an element, as a string.
693    *
694    * @param elem the element whose property is to be retrieved
695    * @param prop the name of the property
696    * @return the property's value
697    */
698   public static String getElementProperty(Element elem, String prop) {
699      return impl.getElementProperty(elem, prop);
700   }
701
702   /**
703    * Gets any named property from an element, as a boolean.
704    *
705    * @param elem the element whose property is to be retrieved
706    * @param prop the name of the property
707    * @return the property's value as a boolean
708    */
709   public static boolean getElementPropertyBoolean(Element elem, String prop) {
710      return impl.getElementPropertyBoolean(elem, prop);
711   }
712
713   /**
714    * Gets any named property from an element, as an int.
715    *
716    * @param elem the element whose property is to be retrieved
717    * @param prop the name of the property
718    * @return the property's value as an int
719    */
720   public static int getElementPropertyInt(Element elem, String prop) {
721      return impl.getElementPropertyInt(elem, prop);
722   }
723
724   /**
725    * Gets the current set of events sunk by a given element.
726    *
727    * @param elem the element whose events are to be retrieved
728    * @return a bitfield describing the events sunk on this element (its possible
729    * values are described in {@link Event})
730    */
731   public static int getEventsSunk(Element elem) {
732     return impl.getEventsSunk(elem);
733   }
734
735   /**
736    * Gets the first child element of the given element.
737    *
738    * @param elem the element whose child is to be retrieved
739    * @return the child element
740    */
741   public static Element getFirstChild(Element elem) {
742     return impl.getFirstChild(elem);
743   }
744
745   /**
746    * Gets the src attribute of an img element. This method is paired with
747    * {@link #setImgSrc(Element, String)} so that it always returns the correct
748    * url.
749    *
750    * @param img a non-null img whose src attribute is to be read.
751    * @return the src url of the img
752    */
753   public static String getImgSrc(Element img) {
754     return impl.getImgSrc(img);
755   }
756
757   /**
758    * Gets an HTML representation of an element's children.
759    *
760    * @param elem the element whose HTML is to be retrieved
761    * @return the HTML representation of the element's children
762    */
763   public static String getInnerHTML(Element elem) {
764     return impl.getInnerHTML(elem);
765   }
766
767   /**
768    * Gets the text contained within an element. If the element has child
769    * elements, only the text between them will be retrieved.
770    *
771    * @param elem the element whose inner text is to be retrieved
772    * @return the text inside this element
773    */
774   public static String getInnerText(Element elem) {
775     return impl.getInnerText(elem);
776   }
777
778   /**
779    * Gets an integer attribute on a given element.
780    *
781    * @param elem the element whose attribute is to be retrieved
782    * @param attr the name of the attribute to be retrieved
783    * @return the attribute's value as an integer
784    * @deprecated Use the more appropriately named
785    * {@link #getElementPropertyInt(Element, String)} instead.
786    */
787   public static int getIntAttribute(Element elem, String attr) {
788     return getElementPropertyInt(elem, attr);
789   }
790
791   /**
792    * Gets an integer attribute on a given element's style.
793    *
794    * @param elem the element whose style attribute is to be retrieved
795    * @param attr the name of the attribute to be retrieved
796    * @return the style attribute's value as an integer
797    */
798   public static int getIntStyleAttribute(Element elem, String attr) {
799     return impl.getIntStyleAttribute(elem, attr);
800   }
801
802   /**
803    * Gets an element's next sibling element.
804    *
805    * @param elem the element whose sibling is to be retrieved
806    * @return the sibling element
807    */
808   public static Element getNextSibling(Element elem) {
809     return impl.getNextSibling(elem);
810   }
811
812   /**
813    * Gets an element's parent element.
814    *
815    * @param elem the element whose parent is to be retrieved
816    * @return the parent element
817    */
818   public static Element getParent(Element elem) {
819     return impl.getParent(elem);
820   }
821
822   /**
823    * Gets an attribute of the given element's style.
824    *
825    * @param elem the element whose style attribute is to be retrieved
826    * @param attr the name of the style attribute to be retrieved
827    * @return the style attribute's value
828    */
829   public static String getStyleAttribute(Element elem, String attr) {
830     return impl.getStyleAttribute(elem, attr);
831   }
832
833   /**
834    * Inserts an element as a child of the given parent element, before another
835    * child of that parent.
836    *
837    * @param parent the parent element
838    * @param child the child element to add to <code>parent</code>
839    * @param before an existing child element of <code>parent</code> before
840    * which <code>child</code> will be inserted
841    */
842   public static void insertBefore(Element parent, Element child, Element before) {
843     impl.insertBefore(parent, child, before);
844   }
845
846   /**
847    * Inserts an element as a child of the given parent element.
848    *
849    * @param parent the parent element
850    * @param child the child element to add to <code>parent</code>
851    * @param index the index before which the child will be inserted (any value
852    * greater than the number of existing children will cause the child
853    * to be appended)
854    */
855   public static void insertChild(Element parent, Element child, int index) {
856     impl.insertChild(parent, child, index);
857   }
858
859   /**
860    * Creates an <code>&lt;option&gt;</code> element and inserts it as a child
861    * of the specified <code>&lt;select&gt;</code> element.
862    *
863    * @param select the <code>&lt;select&gt;</code> element
864    * @param item the text of the new item; cannot be <code>null</code>
865    * @param value the <code>value</code> attribute for the new
866    * <code>&lt;option&gt;</code>; cannot be <code>null</code>
867    * @param index the index at which to insert the child
868    */
869   public static void insertListItem(Element select, String item, String value,
870       int index) {
871     impl.insertListItem(select, item, value, index);
872   }
873
874   /**
875    * Determine whether one element is equal to, or the child of, another.
876    *
877    * @param parent the potential parent element
878    * @param child the potential child element
879    * @return <code>true</code> if the relationship holds
880    * @see #compare(Element, Element)
881    */
882   public static boolean isOrHasChild(Element parent, Element child) {
883     return impl.isOrHasChild(parent, child);
884   }
885
886   /**
887    * Releases mouse capture on the given element. Calling this method has no
888    * effect if the element does not currently have mouse capture.
889    *
890    * @param elem the element to release capture
891    * @see #setCapture(Element)
892    */
893   public static void releaseCapture(Element elem) {
894     if ((sCaptureElem != null) && compare(elem, sCaptureElem)) {
895       sCaptureElem = null;
896     }
897     impl.releaseCapture(elem);
898   }
899
900   /**
901    * Removes a child element from the given parent element.
902    *
903    * @param parent the parent element
904    * @param child the child element to be removed
905    */
906   public static void removeChild(Element parent, Element child) {
907     impl.removeChild(parent, child);
908   }
909
910   /**
911    * Removes the named attribute from the given element.
912    *
913    * @param elem the element whose attribute is to be removed
914    * @param attr the name of the element to remove
915    */
916   public static void removeElementAttribute(Element elem, String attr) {
917     impl.removeElementAttribute(elem, attr);
918   }
919
920   /**
921    * Removes an element from the preview stack. This element will no longer
922    * capture events, though any preview underneath it will begin to do so.
923    *
924    * @param preview the event preview to be removed from the stack
925    */
926   public static void removeEventPreview(EventPreview preview) {
927     // Remove the event preview from the stack. If it was on top,
928 // any preview underneath it will automatically begin to
929 // receive events.
930 sEventPreviewStack.remove(preview);
931   }
932
933   /**
934    * Scrolls the given element into view.
935    *
936    * <p>
937    * This method crawls up the DOM hierarchy, adjusting the scrollLeft and
938    * scrollTop properties of each scrollable element to ensure that the
939    * specified element is completely in view. It adjusts each scroll position by
940    * the minimum amount necessary.
941    * </p>
942    *
943    * @param elem the element to be made visible
944    */
945   public static void scrollIntoView(Element elem) {
946     impl.scrollIntoView(elem);
947   }
948
949   /**
950    * Sets an attribute on the given element.
951    *
952    * @param elem the element whose attribute is to be set
953    * @param attr the name of the attribute to be set
954    * @param value the new attribute value
955    * @deprecated Use the more appropriately named
956    * {@link #setElementProperty(Element, String, String)} instead.
957    */
958   public static void setAttribute(Element elem, String attr, String value) {
959     setElementProperty(elem, attr, value);
960   }
961
962   /**
963    * Sets a boolean attribute on the given element.
964    *
965    * @param elem the element whose attribute is to be set
966    * @param attr the name of the attribute to be set
967    * @param value the attribute's new boolean value
968    * @deprecated Use the more appropriately named
969    * {@link #setElementPropertyBoolean(Element, String, boolean)} instead.
970    */
971   public static void setBooleanAttribute(Element elem, String attr,
972       boolean value) {
973     setElementPropertyBoolean(elem, attr, value);
974   }
975
976   /**
977    * Sets mouse-capture on the given element. This element will directly receive
978    * all mouse events until {@link #releaseCapture(Element)} is called on it.
979    *
980    * @param elem the element on which to set mouse capture
981    */
982   public static void setCapture(Element elem) {
983     sCaptureElem = elem;
984     impl.setCapture(elem);
985   }
986
987   /**
988    * Sets an attribute on a given element.
989    *
990    * @param elem element whose attribute is to be set
991    * @param attr the name of the attribute
992    * @param value the value to which the attribute should be set
993    */
994   public static void setElementAttribute(Element elem, String attr,
995       String value) {
996     impl.setElementAttribute(elem, attr, value);
997   }
998
999   /**
1000   * Sets a property on the given element.
1001   *
1002   * @param elem the element whose property is to be set
1003   * @param prop the name of the property to be set
1004   * @param value the new property value
1005   */
1006  public static void setElementProperty(Element elem, String prop,
1007      String value) {
1008    impl.setElementProperty(elem, prop, value);
1009  }
1010
1011  /**
1012   * Sets a boolean property on the given element.
1013   *
1014   * @param elem the element whose property is to be set
1015   * @param prop the name of the property to be set
1016   * @param value the new property value as a boolean
1017   */
1018  public static void setElementPropertyBoolean(Element elem, String prop,
1019      boolean value) {
1020    impl.setElementPropertyBoolean(elem, prop, value);
1021  }
1022
1023  /**
1024   * Sets an int property on the given element.
1025   *
1026   * @param elem the element whose property is to be set
1027   * @param prop the name of the property to be set
1028   * @param value the new property value as an int
1029   */
1030  public static void setElementPropertyInt(Element elem, String prop,
1031      int value) {
1032    impl.setElementPropertyInt(elem, prop, value);
1033  }
1034
1035  /**
1036   * Sets the {@link EventListener} to receive events for the given element.
1037   * Only one such listener may exist for a single element.
1038   *
1039   * @param elem the element whose listener is to be set
1040   * @param listener the listener to receive {@link Event events}
1041   */
1042  public static void setEventListener(Element elem, EventListener listener) {
1043    impl.setEventListener(elem, listener);
1044  }
1045
1046  /**
1047   * Sets the src attribute of an img element. This method ensures that imgs
1048   * only ever have their contents requested one single time from the server.
1049   *
1050   * @param img a non-null img whose src attribute will be set.
1051   * @param src a non-null url for the img
1052   */
1053  public static void setImgSrc(Element img, String src) {
1054    impl.setImgSrc(img, src);
1055  }
1056
1057  /**
1058   * Sets the HTML contained within an element.
1059   *
1060   * @param elem the element whose inner HTML is to be set
1061   * @param html the new html
1062   */
1063  public static void setInnerHTML(Element elem, String html) {
1064    impl.setInnerHTML(elem, html);
1065  }
1066
1067  /**
1068   * Sets the text contained within an element. If the element already has
1069   * children, they will be destroyed.
1070   *
1071   * @param elem the element whose inner text is to be set
1072   * @param text the new text
1073   */
1074  public static void setInnerText(Element elem, String text) {
1075    impl.setInnerText(elem, text);
1076  }
1077
1078  /**
1079   * Sets an integer attribute on the given element.
1080   *
1081   * @param elem the element whose attribute is to be set
1082   * @param attr the name of the attribute to be set
1083   * @param value the attribute's new integer value
1084   * @deprecated Use the more appropriately named
1085   * {@link #setElementPropertyInt(Element, String, int)} instead.
1086   */
1087  public static void setIntAttribute(Element elem, String attr, int value) {
1088    setElementPropertyInt(elem, attr, value);
1089  }
1090
1091  /**
1092   * Sets an integer attribute on the given element's style.
1093   *
1094   * @param elem the element whose style attribute is to be set
1095   * @param attr the name of the style attribute to be set
1096   * @param value the style attribute's new integer value
1097   */
1098  public static void setIntStyleAttribute(Element elem, String attr,
1099      int value) {
1100    impl.setIntStyleAttribute(elem, attr, value);
1101  }
1102
1103  /**
1104   * Sets the option text of the given select object.
1105   *
1106   * @param select the select object whose option text is being set
1107   * @param text the text to set
1108   * @param index the index of the option whose text should be set
1109   */
1110  public static void setOptionText(Element select, String text, int index) {
1111    impl.setOptionText(select, text, index);
1112  }
1113
1114  /**
1115   * Sets an attribute on the given element's style.
1116   *
1117   * @param elem the element whose style attribute is to be set
1118   * @param attr the name of the style attribute to be set
1119   * @param value the style attribute's new value
1120   */
1121  public static void setStyleAttribute(Element elem, String attr,
1122      String value) {
1123    impl.setStyleAttribute(elem, attr, value);
1124  }
1125
1126  /**
1127   * Sets the current set of events sunk by a given element. These events will
1128   * be fired to the nearest {@link EventListener} specified on any of the
1129   * element's parents.
1130   *
1131   * @param elem the element whose events are to be retrieved
1132   * @param eventBits a bitfield describing the events sunk on this element (its
1133   * possible values are described in {@link Event})
1134   */
1135  public static void sinkEvents(Element elem, int eventBits) {
1136    impl.sinkEvents(elem, eventBits);
1137  }
1138
1139  /**
1140   * Returns a stringized version of the element. This string is for debugging
1141   * purposes and will NOT be consistent on different browsers.
1142   *
1143   * @param elem the element to stringize
1144   * @return a string form of the element
1145   */
1146  public static String toString(Element elem) {
1147    return impl.toString(elem);
1148  }
1149
1150  /**
1151   * This method is called directly by native code when any event is fired.
1152   *
1153   * @param evt the handle to the event being fired.
1154   * @param elem the handle to the element that received the event.
1155   * @param listener the listener associated with the element that received the
1156   * event.
1157   */
1158  static void dispatchEvent(Event evt, Element elem, EventListener listener) {
1159    UncaughtExceptionHandler handler = GWT.getUncaughtExceptionHandler();
1160    if (handler != null) {
1161      dispatchEventAndCatch(evt, elem, listener, handler);
1162    } else {
1163      dispatchEventImpl(evt, elem, listener);
1164    }
1165  }
1166
1167  /**
1168   * This method is called directly by native code when event preview is being
1169   * used.
1170   *
1171   * @param evt a handle to the event being previewed
1172   * @return <code>false</code> to cancel the event
1173   */
1174  static boolean previewEvent(Event evt) {
1175    // If event previews are present, redirect events to the topmost of them.
1176 boolean ret = true;
1177    if (sEventPreviewStack.size() > 0) {
1178      EventPreview preview =
1179        (EventPreview) sEventPreviewStack.get(sEventPreviewStack.size() - 1);
1180      if (!(ret = preview.onEventPreview(evt))) {
1181        // If the preview cancels the event, stop it from bubbling and
1182 // performing its default action.
1183 eventCancelBubble(evt, true);
1184        eventPreventDefault(evt);
1185      }
1186    }
1187
1188    return ret;
1189  }
1190
1191  private static void dispatchEventAndCatch(Event evt, Element elem,
1192      EventListener listener, UncaughtExceptionHandler handler) {
1193    try {
1194      dispatchEventImpl(evt, elem, listener);
1195    } catch (Throwable e) {
1196      handler.onUncaughtException(e);
1197    }
1198  }
1199
1200  private static void dispatchEventImpl(Event evt, Element elem,
1201      EventListener listener) {
1202    // If this element has capture...
1203 if (elem == sCaptureElem) {
1204      // ... and it's losing capture, clear sCaptureElem.
1205 if (eventGetType(evt) == Event.ONLOSECAPTURE) {
1206        sCaptureElem = null;
1207      }
1208    }
1209
1210    // Pass the event to the listener.
1211 listener.onBrowserEvent(evt);
1212  }
1213}
1214

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags