Document.idl

//
// Significant changes since DOM-2 Style:
//
//   1. move styleSheets from separate interface (DocumentStyle) to Document
//   2. addition of selectedStyleSheetSet, lastStyleSheetSet, preferredStyleSheetSet, styleSheetSets, and enableStyleSheetsForSet members
//
// N.B. HTML4 Section 14.3 "External Style Sheets" introduces the concept of a "group [of] alternate style sheets ... under a single style [sheet set] name",
// but does not actually use the term "style sheet set". See http://www.w3.org/TR/html401/present/styles.html#h-14.3 for details.
//
// N.B. According to HTML4 Section 14.3, a "persistent style sheet ... must apply in addition to any alternate style sheet".
//
// N.B. HTML4 Section 14.3 distinguishes the three categories of style sheets as follows:
//
//   * persistent - @rel='stylesheet', @title is missing (or empty string?)
//   * preferred  - @rel='stylesheet', @title is present (and non-empty?)
//   * alternate  - @rel='alternate stylesheet', @title is present (and non-empty?)
//
// Also, HTML5 effectively defines:
//
//   * ignored    - @rel='alternate stylesheet', @title is missing (or is empty string?) - in this case, LinkStyle.style must evaluate to null
//
// N.B. HTML4 Section 4.3 allows author to specify the default preferred style sheet [set]... [presumably in the case that there are multiple preferred style sheet sets]:
//
//   * in content - <META http-equiv="Default-Style" content="compact">
//   * in http - e.g., using response header - "Default-Style: compact"
//   * if multiple of the above forms are present, then the LAST one [seen or parsed] takes precedence; HOWEVER, if two or more LINK elements specify preferred style
//     [sheet sets], the FIRST one present in the document takes precedence;
//   * preferred style sheets specified using the above (META or HTTP header equivalent) take precedence over those specified with LINK
//
// N.B. CSSOM Draft presently employs the term "Style Sheet Collection"
//
// Spec Issues:
//
//   1. need to specify which style sheets are included in styleSheets, and in which order:
//
//      * from Link HTTP header reference
//      * from <?xml-stylesheet ...?>
//      * from LINK element, @rel='stylesheet'|'alternate stylesheet'
//      * from STYLE element
//
//   2. for purpose of comparing two titled (named) style sheets, is title (name) compared on case-sensitive or case-insensitive basis
//
//   3. CSSOM 6.2 appears to imply that one can create a CSSStyleSheet (or StyleSheet) object and add it to a Document. However, that is not the case; rather
//      it is necessary to create an HTMLLinkElement or HTMLStyleElement element to indirectly create an empty StyleSheet, then this element can be added to the Document.
//

partial interface Document {

  [Documentation=
   "<p>The {@name} {@type} must return a <code>StyleSheetList</code> sequence representing\
    the <span>document style sheets</span>.</p>\
    <p class='note'>Because of historical IDL limitations the {@name} {@type}\
    used to be on a separate interface, <code>DocumentStyle</code>.</p>"
  ]
  readonly attribute StyleSheetList styleSheets;                // DOM-2 - defined on DocumentStyle interface

  [Documentation=
   "<p>The {@name} {@type} must, on getting, must run these steps:</p>\
    <ol>\
      <li><p>If there is a single <span>enabled style sheet set</span> and no\
      other <span>document style sheets</span> with a non-empty\
      <span>style sheet title</span> have the\
      <span>style sheet disabled flag</span> unset, return the\
      <span>style sheet set name</span> of the\
      <span>enabled style sheet set</span> and terminate these steps.</li>\
      \
      <li><p>Otherwise, if <span title='style sheet'>style sheets</span> from\
      different <span title='style sheet set'>style sheet sets</span> have\
      their <span>style sheet disabled flag</span> unset, return\
      null and terminate these steps.</li>\
      \
      <li>\
       <p>Otherwise, return the empty string.</p>\
      \
       <p class='note'>At this point either all\
       <span title='style sheet'>style sheets</span> with a non-empty\
       <span>style sheet title</span> have the\
       <span>style sheet disabled flag</span> set, or there are no such\
       <span title='style sheet'>style sheets</span>.</p>\
      </li>\
     </ol>\
    \
    <p>On setting the\
    <code title='dom-Document-selectedStyleSheetSet'>selectedStyleSheetSet</code>\
    attribute these steps must be run:</p>\
    \
    <ol>\
      <li><p>If the value is null terminate this set of steps.</p></li>\
      <li><p>Otherwise, <span>select a style sheet set</span> with as name the\
      value passed.</p></li>\
    </ol>\
    \
    <p>From the DOM's perspective, all views have the same\
    <code title='dom-Document-selectedStyleSheetSet'>selectedStyleSheetSet</code>.\
    If a user agent supports multiple views with different selected\
    alternative style sheets, then this attribute (and the\
    <code>StyleSheet</code> interface's\
    <code title='dom-StyleSheet-disabled'>disabled</code> attribute)\
    must return and set the value for the default\
    view.</p>"
  ]
  attribute DOMString? selectedStyleSheetSet;                   // new

  [Documentation=
   "<p>The {@name} {@type} must  return the <span>last style sheet set name</span>.</p>\
    <p class='note'>This attribute is initially null.</p>"
  ]
  readonly attribute DOMString? lastStyleSheetSet;              // new

  [Documentation=
   "<p>The {@name} {@type} must  return the <span>preferred style sheet set name</span>.</p>\
    <p class='note'>Unlike <code title='dom-Document-lastStyleSheetSet'>lastStyleSheetSet</code>,\
    this attribute is initially the empty string.</p>"
  ]
  readonly attribute DOMString? preferredStyleSheetSet;         // new

  [Documentation=
   "<p>The {@name} {@type} must  return a list of the <span title='style sheet set name'>style\
    sheet set names</span> of the <span title='style sheet set'>style sheet sets</span>, in order\
    of the <span>document style sheets</span>.</p>"
  ]
  readonly attribute DOMStringList styleSheetSets;              // new

  [Documentation=
   "<p>The {@name} {@type} must, when invoked, run these steps:</p>\
    <ol>\
      <li><p>If <var>name</var> is null terminate these steps.</p></li>\
      <li><p><span>Enable a style sheet set</span> with name <var>name</var>.</p></li>\
    </ol>\
    <p class='note'><span title='Style sheet'>Style sheets</span> with an\
    empty <span>style sheet title</span> are never affected by this method.\
    This method does not change the values of the\
    <code title='dom-Document-lastStyleSheetSet'>lastStyleSheetSet</code> or\
    <code title='dom-Document-preferredStyleSheetSet'>preferredStyleSheetSet</code> attributes.</p>"
  ]
  void enableStyleSheetsForSet(DOMString? name);                // new

};