Java tutorial
/** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ package org.waveprotocol.wave.client.common.util; import com.google.gwt.core.client.JavaScriptException; import com.google.gwt.core.client.JavaScriptObject; import com.google.gwt.core.client.JsArray; import com.google.gwt.dom.client.DivElement; import com.google.gwt.dom.client.Document; import com.google.gwt.dom.client.Element; import com.google.gwt.dom.client.Node; import com.google.gwt.dom.client.NodeList; import com.google.gwt.dom.client.Style.Display; import com.google.gwt.user.client.Event; import com.google.gwt.user.client.ui.impl.FocusImpl; import org.waveprotocol.wave.model.document.util.Point; import org.waveprotocol.wave.model.util.CollectionUtils; import org.waveprotocol.wave.model.util.IdentitySet; import org.waveprotocol.wave.model.util.Preconditions; import org.waveprotocol.wave.model.util.ReadableStringSet; import org.waveprotocol.wave.model.util.StringSet; /** * Helper methods * * Some adapted from UIElement, so the interface could do with increasing consistency * * TODO(danilatos,user): Clean up / organise methods in this class * * @author danilatos@google.com (Daniel Danilatos) */ public class DomHelper { /** * Describes the editability of an element, ignoring its context (ancestor nodes, etc). */ public enum ElementEditability { /** The element is definitely editable */ EDITABLE, /** The element is not editable */ NOT_EDITABLE, /** The element is "neutral", which means its editability is inherited */ NEUTRAL } /** Webkit editability controlling css property */ public static final String WEBKIT_USER_MODIFY = "-webkit-user-modify"; /** * Interface for receiving low-level javascript events */ public interface JavaScriptEventListener { /** * @param name The event name, without any leading "on-" prefix * @param event The native event object */ void onJavaScriptEvent(String name, Event event); } private DomHelper() { } /** * Return true if the element is a text box * @param element * @return true if the element is a text box */ public static boolean isTextBox(Element element) { return "input".equalsIgnoreCase(element.getTagName()) && "text".equalsIgnoreCase(element.getAttribute("type")); } /** * @param element * @param styleName * @return true if the element or an ancestor has the given stylename */ public static boolean hasStyleOrAncestorHasStyle(Element element, String styleName) { while (element != null) { if (element.getClassName().indexOf(styleName) >= 0) { return true; } element = element.getParentElement(); } return false; } /** * Cast to old-style Element. * * TODO(danilatos): Deprecate this method when GWT has updated everything to not require * the old style Element. * * @param element new style element * @return old style element */ public static com.google.gwt.user.client.Element castToOld(Element element) { return element.cast(); } /** * Create a div with the given style name set. Convenience method because * this is such a common task * @param styleName * @return The created div element */ public static DivElement createDivWithStyle(String styleName) { DivElement d = Document.get().createDivElement(); d.setClassName(styleName); return d; } /** * Focus the element, if possible * @param element */ public static void focus(Element element) { // NOTE(user): This may not work for divs, rather use getFocusImplForPanel // for divs. try { FocusImpl.getFocusImplForWidget().focus(castToOld(element)); } catch (Exception e) { // Suppress null pointer condition } } /** * Blur the element, if possible * @param element * * NOTE(user): Dan thinks this method should be deprecated, but is not * sure why... Dan, please update once you remember. */ public static void blur(Element element) { FocusImpl.getFocusImplForWidget().blur(castToOld(element)); } /** * Sets display:none on the given element if isVisible is false, and clears * the display css property if isVisible is true. * * This idiom is commonly switched on a boolean, so this method takes care of * the 5 lines of boilerplate. * * @param element * @param isVisible */ public static void setDisplayVisible(Element element, boolean isVisible) { if (isVisible) { element.getStyle().clearDisplay(); } else { element.getStyle().setDisplay(Display.NONE); } } /** * Finds the index of an element in its parent's list of child elements. * This is not the same as {@link #findChildIndex(Node)}, since it ignores * non-element nodes. It is in line with the element-only view of a collection * of children exposed by {@link Element#getFirstChildElement()} and * {@link Element#getNextSiblingElement()}. * * @param child an element * @return the index of {@code child}, or -1 if {@code child} is not a child * of its parent. * @see #findChildIndex(Node) */ public static final int findChildElementIndex(Element child) { Element parent = child.getParentElement(); Element e = parent.getFirstChildElement(); int i = 0; while (e != null) { if (e.equals(child)) { return i; } else { e = e.getNextSiblingElement(); i++; } } return -1; } /** * Wrap at least one node * @param with The element in which to wrap the nodes * @param from First node to wrap * @param toExcl Node after end of wrap range */ public static void wrap(Element with, Node from, Node toExcl) { from.getParentNode().insertBefore(with, from); moveNodes(with, from, toExcl, null); } /** * @param element The element to unwrap. If not attached, does nothing. */ public static void unwrap(Element element) { if (element.hasParentElement()) { moveNodes(element.getParentElement(), element.getFirstChild(), null, element.getNextSibling()); element.removeFromParent(); } } /** * Insert before, but for a range of adjacent siblings * * TODO(danilatos): Apparently safari and firefox let you do this in one * go using ranges, which could be a lot faster than iterating manually. * Create a deferred binding implementation. * @param parent * @param from * @param toExcl * @param refChild */ public static void moveNodes(Element parent, Node from, Node toExcl, Node refChild) { for (Node n = from; n != toExcl;) { Node m = n; n = n.getNextSibling(); parent.insertBefore(m, refChild); } } /** * Remove nodes in the given range from the DOM * @param from * @param toExcl */ public static void removeNodes(Node from, Node toExcl) { if (from == null || !from.hasParentElement()) { return; } for (Node n = from; n != toExcl && n != null;) { Node r = n; n = n.getNextSibling(); r.removeFromParent(); } } /** * Remove all children from an element * @param element */ public static void emptyElement(Element element) { while (element.getFirstChild() != null) { element.removeChild(element.getFirstChild()); } } /** * Ensures the given container contains exactly one child, the given one. * Provides the important property that if the container is already the parent * of the given child, then the child is not removed and re-added, it is left * there; any siblings, if present, are removed. * * @param container * @param child */ public static void setOnlyChild(Element container, Node child) { if (child.getParentElement() != container) { // simple case emptyElement(container); container.appendChild(child); } else { // tricky case - avoid removing then re-appending the same child while (child.getNextSibling() != null) { child.getNextSibling().removeFromParent(); } while (child.getPreviousSibling() != null) { child.getPreviousSibling().removeFromParent(); } } } /** * Swaps out the old element for the new element. * The old element's children are added to the new element * * @param oldElement * @param newElement */ public static void replaceElement(Element oldElement, Element newElement) { // TODO(danilatos): Profile this to see if it is faster to move the nodes first, // and then remove, or the other way round. Profile and optimise some of these // other methods too. Take dom mutation event handlers being registered into account. if (oldElement.hasParentElement()) { oldElement.getParentElement().insertBefore(newElement, oldElement); oldElement.removeFromParent(); } DomHelper.moveNodes(newElement, oldElement.getFirstChild(), null, null); } /** * Make an element editable or not * * @param element * @param whiteSpacePreWrap Whether to additionally turn on the white space * pre wrap property. If in doubt, set to true. This is what we use for * the editor. So for any concurrently editable areas and such, we must * use true. If false, does nothing (it does not clear the property). * @param isEditable * @return the same element for convenience */ public static Element setContentEditable(Element element, boolean isEditable, boolean whiteSpacePreWrap) { if (UserAgent.isSafari()) { // We MUST use the "plaintext-only" variant to prevent nasty things like // Apple+B munging our dom without giving us a key event. // Assertion in GWT stuffs this up... fix GWT, in the meantime use a string map // element.getStyle().setProperty("-webkit-user-modify", // isEditable ? "read-write-plaintext-only" : "read-only"); JsoView.as(element.getStyle()).setString("-webkit-user-modify", isEditable ? "read-write-plaintext-only" : "read-only"); } else { element.setAttribute("contentEditable", isEditable ? "true" : "false"); } if (whiteSpacePreWrap) { // More GWT assertion fun! JsoView.as(element.getStyle()).setString("white-space", "pre-wrap"); } return element; } /** * Checks whether the given DOM element is editable, either explicitly or * inherited from its ancestors. * @param e Element to check */ public static boolean isEditable(Element e) { // special early-exit for problematic shadow dom: if (isUnreadable(e)) { return true; } Element docElement = Document.get().getDocumentElement(); do { ElementEditability editability = getElementEditability(e); if (editability == ElementEditability.NEUTRAL) { if (e == docElement) { return false; } e = e.getParentElement(); } else { return editability == ElementEditability.EDITABLE ? true : false; } } while (e != null); // NOTE(danilatos): We didn't hit the body. The only way I know that this can happen // is if the browser gave us a text node from its SHADOW dom, e.g. in a text box, // which doesn't have any text node children. I've observed the parent of this text node // to be reported as a div, and the parent of that div to be null. return true; } public static ElementEditability getElementEditability(Element elem) { // NOTE(danilatos): This is not necessarily accurate in 100% of situations, with weird // combinations of editability/enabled etc attributes and tagnames... String tagName = null; try { tagName = elem.getTagName(); } catch (Exception exception) { // Couldn't get access to the tag name for some reason (see b/2314641). } if (tagName != null) { tagName = tagName.toLowerCase(); if (tagName.equals("input") || tagName.equals("textarea")) { return ElementEditability.EDITABLE; } } return getContentEditability(elem); } /** * @param element * @return editability in terms of content-editable only (ignore tag names) */ public static ElementEditability getContentEditability(Element element) { String editability = null; if (UserAgent.isSafari()) { JsoView style = JsoView.as(element.getStyle()); editability = style.getString(WEBKIT_USER_MODIFY); if ("read-write-plaintext-only".equalsIgnoreCase(editability) || "read-write".equalsIgnoreCase(editability)) { return ElementEditability.EDITABLE; } else if (editability != null && !editability.isEmpty()) { return ElementEditability.NOT_EDITABLE; } // NOTE(danilatos): The css property overrides the contentEditable attribute. // Still keep going just to check the content editable prop, if no css property set. } try { editability = element.getAttribute("contentEditable"); } catch (JavaScriptException e) { String elementString = "<couldn't get element string>"; String elementTag = "<couldn't get element tag>"; try { elementString = element.toString(); } catch (Exception exception) { } try { elementTag = element.getTagName(); } catch (Exception exception) { } StringBuilder sb = new StringBuilder(); sb.append("Couldn't get the 'contentEditable' attribute for element '"); sb.append(elementString).append("' tag name = ").append(elementTag); throw new RuntimeException(sb.toString(), e); } if (editability == null || editability.isEmpty()) { return ElementEditability.NEUTRAL; } else { return "true".equalsIgnoreCase(editability) ? ElementEditability.EDITABLE : ElementEditability.NOT_EDITABLE; } } /** * Sets the spell check attribute on the element. * @param enabled true to enable spell check, false to disable. */ public static void setNativeSpellCheck(Element element, boolean enabled) { element.setAttribute("spellcheck", enabled ? "true" : "false"); } /** * Makes an element, and all its descendant elements, unselectable. */ public static void makeUnselectable(Element e) { if (UserAgent.isIE()) { e.setAttribute("unselectable", "on"); e = e.getFirstChildElement(); while (e != null) { makeUnselectable(e); e = e.getNextSiblingElement(); } } } /** * Used to remove event handlers from elements * * @see DomHelper#registerEventHandler(Element, String, JavaScriptEventListener) */ public static final class HandlerReference extends JavaScriptObject { /***/ protected HandlerReference() { } /** * Unregister a handler registered with * {@link #registerEventHandler(Element, String, JavaScriptEventListener)} or * {@link #registerEventHandler(Element, String, boolean, JavaScriptEventListener)} * * @return true if the handler was unregistered, false if unregister had * already been called. */ public native boolean unregister() /*-{ var el = this.$el; if (el == null) { return false; } if (el.removeEventListener) { el.removeEventListener(this.$ev, this, this.$cp); } else if (el.detachEvent) { el.detachEvent('on' + this.$ev, this); } else { el['on' + this.$ev] = null; } this.$ev = null; return true; }-*/; } /** * A set of {@link HandlerReference} for when registering and unregistering a * handler on multiple events at once. */ public static final class HandlerReferenceSet { public IdentitySet<HandlerReference> references = CollectionUtils.createIdentitySet(); public void unregister() { Preconditions.checkState(references != null, "References already unregistered"); references.each(new IdentitySet.Proc<HandlerReference>() { @Override public void apply(HandlerReference ref) { ref.unregister(); } }); references = null; } } /** * A low level way to register event handlers on dom elements. This differs * from sinkEvents in that it has nothing to do with widgets, and also allows * specifying any event name as a string. * * NOTE(danilatos): Care must be taken when using this low-level technique, * you will need to handle your own cleanup to avoid memory leaks. * * @param el The dom element on which to listen to events * @param eventName The name of the event, without any "on-" prefix * @param listener * @return a handler to be used with de-registering */ public static HandlerReference registerEventHandler(Element el, String eventName, JavaScriptEventListener listener) { return registerEventHandler(el, eventName, false, listener); } // TODO(danilatos): Split the implementation out into browser-specific versions /** * Same as {@link #registerEventHandler(Element, String, JavaScriptEventListener)} * except provides the (non-cross-browser) capture parameter */ public static native HandlerReference registerEventHandler(Element el, String eventName, boolean capture, JavaScriptEventListener listener) /*-{ var func = $entry(function(e) { var evt = e || $wnd.event; listener. @org.waveprotocol.wave.client.common.util.DomHelper.JavaScriptEventListener::onJavaScriptEvent(Ljava/lang/String;Lcom/google/gwt/user/client/Event;) (eventName, evt); }); if (el.addEventListener) { el.addEventListener(eventName, func, capture); } else if (el.attachEvent) { el.attachEvent('on' + eventName, func); } else { el['on' + eventName.toLowerCase()] = func; } // Setup handler reference object func.$ev = eventName; func.$cp = capture; func.$el = el; return func; }-*/; /** * Registers a listener for multiple browser events in one go * * @param el element to listen on * @param eventNames set of events * @param listener * @return a reference set to be used for unregistering the handler for all * events in one go */ public static HandlerReferenceSet registerEventHandler(final Element el, ReadableStringSet eventNames, final JavaScriptEventListener listener) { Preconditions.checkArgument(!eventNames.isEmpty(), "registerEventHandler: Event set is empty"); final HandlerReferenceSet referenceSet = new HandlerReferenceSet(); eventNames.each(new StringSet.Proc() { @Override public void apply(String eventName) { referenceSet.references.add(registerEventHandler(el, eventName, listener)); } }); return referenceSet; } /** * @return true if it is an element */ public static boolean isElement(Node n) { return n.getNodeType() == Node.ELEMENT_NODE; } /** * @return true if it is a text node */ public static boolean isTextNode(Node n) { return n.getNodeType() == Node.TEXT_NODE; } /** * Finds the index of an element among its parent's children, including * text nodes. * @param toFind the node to retrieve the index for * @return index of element * * TODO(danilatos): This could probably be done faster with * a binary search using text ranges. * TODO(lars): adapt to non standard browsers. * TODO(lars): is there a single js call that does this? */ public static native int findChildIndex(Node toFind) /*-{ var parent = toFind.parentNode; var count = 0, child = parent.firstChild; while (child) { if (child == toFind) return count; if (child.nodeType == 1 || child.nodeType == 3) ++count; child = child.nextSibling; } return -1; }-*/; /** * The last child of element this element. If there is no such element, this * returns null. */ // GWT forgot to add Element.getLastChildElement(), to be symmetric with // Element.getFirstChildElement(). public static native Element getLastChildElement(Element elem) /*-{ var child = elem.lastChild; while (child && child.nodeType != 1) child = child.previousSibling; return child; }-*/; /** * Gets a list of descendants of e that match the given class name. * * If the browser has the native method, that will be called. Otherwise, it * traverses descendents of the given element and returns the list of elements * with matching classname. * * @param e * @param className */ public static NodeList<Element> getElementsByClassName(Element e, String className) { if (QuirksConstants.SUPPORTS_GET_ELEMENTS_BY_CLASSNAME) { return getElementsByClassNameNative(e, className); } else { NodeList<Element> all = e.getElementsByTagName("*"); if (all == null) { return null; } JsArray<Element> ret = JavaScriptObject.createArray().cast(); for (int i = 0; i < all.getLength(); ++i) { Element item = all.getItem(i); if (className.equals(item.getClassName())) { ret.push(item); } } return ret.cast(); } } private static native NodeList<Element> getElementsByClassNameNative(Element e, String className) /*-{ return e.getElementsByClassName(className); }-*/; /** * Checks whether the properties of given node cannot be accessed (by testing the nodeType). * * It is sometimes the case where we need to access properties of a Node, but the properties * on that node are not readable (for example, a shadow node like a div created to hold the * selection within an input field). * * In these cases, when the javascript cannot access the node's properties, any attempt to do * so may cause an internal permissions exception. This method swallows the exception and uses * its existence to indicate whether or not the node is actually readable. * * @param n Node to check * @return Whether or not the node can have properties read. */ public static boolean isUnreadable(Node n) { try { n.getNodeType(); return false; } catch (RuntimeException e) { return true; } } /** * Converts a nodelet/offset pair to a Point of Node. * Just a simple mapping, it is agnostic to inconsistencies, filtered views, etc. * @param node * @param offset * @return html node point */ public static Point<Node> nodeOffsetToNodeletPoint(Node node, int offset) { if (isTextNode(node)) { return Point.inText(node, offset); } else { Element container = node.<Element>cast(); return Point.inElement(container, nodeAfterFromOffset(container, offset)); } } /** * Given a node/offset pair, return the node after the point. * * @param container * @param offset */ public static Node nodeAfterFromOffset(Element container, int offset) { return offset >= container.getChildCount() ? null : container.getChild(offset); } }