Changes between Version 1 and Version 2 of TraversingShadowDOMTree

Timestamp:

May 8, 2012 6:44:00 PM (12 years ago)

Author:

hayato@chromium.org

Comment:

--

TraversingShadowDOMTree

@@ -2 +2 @@
 = Traversing Shadow DOM Tree =
 
-This page explains how to use [https://trac.webkit.org/browser/trunk/Source/WebCore/dom/ComposedShadowTreeWalker.cpp ComposedShadowTreeWalker] ComposedShadowTreeWalker class, which enables you to traverse nodes in composed shadow tree order.
+This page explains how to use [https://trac.webkit.org/browser/trunk/Source/WebCore/dom/ComposedShadowTreeWalker.cpp ComposedShadowTreeWalker] class, which enables you to traverse nodes in composed shadow tree order.
 
 = Background =
@@ -20 +20 @@
      └─F      └─J               └─<M select=None>
                                    └─N
-
-  [SR]: ShadowRoot
-  <X select=Y>: InsertionPoint, called X, which selects Y.
+  Notation:
+    [SR]: ShadowRoot
+    <X select=Y>: InsertionPoint, called X, which selects Y.
 }}}
 
@@ -42 +42 @@
      ├─L
      └─N
+
+* I left SR1 and SR2 in the picture for the convenience. These nodes are not rendered.
 }}}
 
@@ -50 +52 @@
 
 {{{
-for (ComposedShadowDOMTreeWalker walker(nodeA); walker.get(); walker.next()) {
-    printNode(walker.get())
-}
+for (ComposedShadowDOMTreeWalker walker(nodeA); walker.get(); walker.next())
+    printNode(walker.get());
 }}}
 
@@ -66 +67 @@
   * walker.lastChild()
 
-These provide similar functionality to functions defined in WebCore::Node, but will traverse  composed shadow tree order, not original DOM tree order.
+These provide similar functionality to functions defined in WebCore::Node, but will traverse nodes in composed shadow tree order, not original DOM tree order.
 These function doesn’t return the result node. All returns ‘void’. Instead, these will update the walker’s internal state, a current visited node. You can get the current visited node by walker.get() function.
 
@@ -81 +82 @@
 
 Notes:
-1. Some nodes (E, F and I) do not participate in the composed shadow tree because they are children (or descendants) of shadow host, but are not distributed. These nodes are treated as separated ‘islands’. e.g. E’s parent() is null, not B.
-2. You could not pass an active InsertionPoint (H, K and M) or a ShadowRoot as a starting node. That should trigger an assertion error.
+  1. Some nodes (E, F and I) do not participate in the composed shadow tree because they are children (or descendants) of shadow host, but are not distributed. These nodes are treated as separated ‘islands’. e.g. E’s parent() is null, not B.
+  2. You could not pass an active InsertionPoint (H, K and M) or a ShadowRoot as a starting node. That should trigger an assertion error.
 
 
@@ -93 +94 @@
 }}}
 
-If a walker is constructed with a policy of DoNotCrossUpperBoundary, youngest ShadowRoots will be also a candidate of visiting nodes and won’t be skipped. Youngest ShadowRoots will act as a top-most node in scope, like a Document node in original DOM tree.
+If a walker is constructed with a policy of `DoNotCrossUpperBoundary`, youngest ShadowRoots will be also a candidate of visiting nodes and won’t be skipped. Youngest ShadowRoots will act as a top-most node in scope, like a Document node in original DOM tree.
 
-The following is the result in case of DoNotCrossUpperBoundary policy:
+The following is the result if you use a walker with DoNotCrossUpperBoundary policy:
 
 ||  || B  || SR1 ||  G || SR2 || C ||
@@ -103 +104 @@
 || previous() ||   A  ||    null ||      SR1   ||      null ||   SR2 ||
 
+
 = Hosting Multiple Shadow Roots = 
 
@@ -109 +111 @@
 = Error cases =
 
-* In Policy of CrossBounary (default):
-You cannot pass an active InsertionPoint or ShadowRoot as a starting node.
+  * With a `CrossBoundary` (default) policy: You cannot pass an active InsertionPoint or ShadowRoot as a starting node.
 
-* In Policy of DoNotCrossUpperBoundary
-You cannot pass an active InsertionPoint or non-youngest ShadowRoot as a starting node.
+  * With a `DoNotCrossUpperBoundary` policy: You cannot pass an active InsertionPoint or non-youngest ShadowRoot as a starting node.
 
-You cannot call any traversal functions if the current visited node is null.
+  * You cannot call any traversal functions if the current visited node is null.
 
 = Performance = 
@@ -121 +121 @@
 To be compared to Node::traverseNextNode() function, walker::next() is about 6 times slower. The result of a micro benchmark is here:
 https://bugs.webkit.org/show_bug.cgi?id=79197#c33
-* The result is based on old APIs. The current walker is a bit faster than old APIs.
-I am going to improve the performance here: https://bugs.webkit.org/show_bug.cgi?id=82702
+
+The result is based on old APIs. The current walker is a bit faster than old APIs. I am going to improve the performance here: https://bugs.webkit.org/show_bug.cgi?id=82702
 
 = Actual Clients = 
@@ -128 +128 @@
 == Focus Controller ==
 
-FocusController (*1) started to use ComposedShadowTreeWalker to traverse composed shadow DOM tree. That’s good example about how to use APIs. That also uses DoNotCrossUpperBoundary policy since Focus navigation should be scoped in each Shadow DOM subtree according to the current Shadow DOM spec. Although FocusNavigation is complex since it should consider each shadow DOM subteee as a ‘scope’, the APIs made implementations much easier since much complex works are done within APIs.
-
-*1: https://trac.webkit.org/browser/trunk/Source/WebCore/page/FocusController.cpp
+[https://trac.webkit.org/browser/trunk/Source/WebCore/page/FocusController.cpp FocusController] started to use ComposedShadowTreeWalker to traverse composed shadow DOM tree. That’s good example about how to use APIs. That also uses DoNotCrossUpperBoundary policy since Focus navigation should be scoped in each Shadow DOM subtree according to the current Shadow DOM spec. Although FocusNavigation is complex since it should consider each shadow DOM subteee as a ‘scope’, the APIs made implementations much easier since much complex works are done within APIs.
 
 == Event Dispatcher ==