Changes between Version 1 and Version 2 of TraversingShadowDOMTree


Ignore:
Timestamp:
May 8, 2012 6:44:00 PM (8 years ago)
Author:
hayato@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TraversingShadowDOMTree

    v1 v2  
    22= Traversing Shadow DOM Tree =
    33
    4 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.
     4This 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.
    55
    66= Background =
     
    2020     └─F      └─J               └─<M select=None>
    2121                                   └─N
    22 
    23   [SR]: ShadowRoot
    24   <X select=Y>: InsertionPoint, called X, which selects Y.
     22  Notation:
     23    [SR]: ShadowRoot
     24    <X select=Y>: InsertionPoint, called X, which selects Y.
    2525}}}
    2626
     
    4242     ├─L
    4343     └─N
     44
     45* I left SR1 and SR2 in the picture for the convenience. These nodes are not rendered.
    4446}}}
    4547
     
    5052
    5153{{{
    52 for (ComposedShadowDOMTreeWalker walker(nodeA); walker.get(); walker.next()) {
    53     printNode(walker.get())
    54 }
     54for (ComposedShadowDOMTreeWalker walker(nodeA); walker.get(); walker.next())
     55    printNode(walker.get());
    5556}}}
    5657
     
    6667  * walker.lastChild()
    6768
    68 These provide similar functionality to functions defined in WebCore::Node, but will traverse composed shadow tree order, not original DOM tree order.
     69These provide similar functionality to functions defined in WebCore::Node, but will traverse nodes in composed shadow tree order, not original DOM tree order.
    6970These 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.
    7071
     
    8182
    8283Notes:
    83 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.
    84 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.
     84  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.
     85  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.
    8586
    8687
     
    9394}}}
    9495
    95 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.
     96If 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.
    9697
    97 The following is the result in case of DoNotCrossUpperBoundary policy:
     98The following is the result if you use a walker with DoNotCrossUpperBoundary policy:
    9899
    99100||  || B  || SR1 ||  G || SR2 || C ||
     
    103104|| previous() ||   A  ||    null ||      SR1   ||      null ||   SR2 ||
    104105
     106
    105107= Hosting Multiple Shadow Roots =
    106108
     
    109111= Error cases =
    110112
    111 * In Policy of CrossBounary (default):
    112 You cannot pass an active InsertionPoint or ShadowRoot as a starting node.
     113  * With a `CrossBoundary` (default) policy: You cannot pass an active InsertionPoint or ShadowRoot as a starting node.
    113114
    114 * In Policy of DoNotCrossUpperBoundary
    115 You cannot pass an active InsertionPoint or non-youngest ShadowRoot as a starting node.
     115  * With a `DoNotCrossUpperBoundary` policy: You cannot pass an active InsertionPoint or non-youngest ShadowRoot as a starting node.
    116116
    117 You cannot call any traversal functions if the current visited node is null.
     117  * You cannot call any traversal functions if the current visited node is null.
    118118
    119119= Performance =
     
    121121To be compared to Node::traverseNextNode() function, walker::next() is about 6 times slower. The result of a micro benchmark is here:
    122122https://bugs.webkit.org/show_bug.cgi?id=79197#c33
    123 * The result is based on old APIs. The current walker is a bit faster than old APIs.
    124 I am going to improve the performance here: https://bugs.webkit.org/show_bug.cgi?id=82702
     123
     124The 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
    125125
    126126= Actual Clients =
     
    128128== Focus Controller ==
    129129
    130 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.
    131 
    132 *1: https://trac.webkit.org/browser/trunk/Source/WebCore/page/FocusController.cpp
     130[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.
    133131
    134132== Event Dispatcher ==